From 6c745ea8f84c0f562efb69e26d50d9568f301357 Mon Sep 17 00:00:00 2001 From: Kazem Alghasi Date: Sun, 4 Oct 2026 03:17:35 +0330 Subject: [PATCH] docs: localize and restructure project documentation Refactor core documentation files to Persian and introduce a deployment handoff guide. - Translate `AGENT.md`, `CLIENT_DELIVERY.md`, and `README.md` to Persian for better local stakeholder alignment - Restructure `AGENT.md` with improved technical specifications and versioning - Update `CLIENT_DELIVERY.md` with localized status legends and requirement tables - Enhance `README.md` with detailed feature lists and improved formatting - Add `DEPLOYMENT_HANDOFF.md` to facilitate production deployment processes --- AGENT.md | 395 ++++++++++++--------- CLIENT_DELIVERY.md | 799 +++++++++++++++++++++--------------------- DEPLOYMENT_HANDOFF.md | 233 ++++++++++++ README.md | 325 ++++++++--------- 4 files changed, 1028 insertions(+), 724 deletions(-) create mode 100644 DEPLOYMENT_HANDOFF.md diff --git a/AGENT.md b/AGENT.md index d7fa3eb..8bdbeea 100644 --- a/AGENT.md +++ b/AGENT.md @@ -1,145 +1,188 @@ -🎯 خلاصه پروژه -سیستم مدیریت لجستیک بین‌المللی با معماری Headless (Laravel 11 به‌عنوان بک‌اند، WordPress به‌عنوان فرانت‌اند، Filament 3.3 به‌عنوان پنل مدیریت). جایگزین فرآیندهای دستی مبتنی بر اکسل شده و از Multi-Package، فاکتور گمرکی (Invoice)، کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید PDF با بارکد، فلوی تأیید سفارش، تعهدنامه، SMS کاوه‌نگار، سیستم اعتبار چندارزی و سیستم رهگیری پیشرفته پشتیبانی می‌کند. +# راهنمای ایجنت — پروژهٔ IFNEX Logistics -وضعیت فعلی: فازهای ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شده‌اند. فاز ۳.۶ (اصلاحات جلسه کارفرما) حدود ۹۵٪ انجام شده است. در این جلسه موارد زیر تکمیل شد: +> **تاریخ:** ۲۰۲۶-۱۰-۰۴ +> **نسخه:** ۱.۳ +> **تهیه‌کننده:** VernaSoft Group — Kazem Alghasi + +--- + +## ۱. خلاصهٔ پروژه + +سیستم مدیریت لجستیک بین‌المللی با معماری Headless: **Laravel 11** به‌عنوان بک‌اند، **WordPress** به‌عنوان فرانت‌اند و **Filament 3.3** به‌عنوان پنل مدیریت. این سیستم جایگزین فرآیندهای دستی مبتنی بر اکسل شده و از Multi-Package، فاکتور گمرکی، کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید PDF با بارکد، فلوی تأیید سفارش، تعهدنامه، SMS کاوه‌نگار، سیستم اعتبار چندارزی و رهگیری پیشرفته پشتیبانی می‌کند. + +### وضعیت فعلی + +فازهای ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شده‌اند. فاز ۳.۶ (اصلاحات جلسهٔ کارفرما) حدود ۹۵٪ انجام شده است: + +- [x] فلوی کامل سفارش (ثبت ← تأیید ← تعهدنامه ← پرداخت) — تست End-to-End +- [x] بازطراحی داشبورد و Login پنل Filament (هویت بصری navy + amber) +- [x] بازطراحی PDFهای AWB، Invoice و Label (dompdf، چیدمان جدولی) +- [x] صفحهٔ «وضعیت مالی مشتری» در پنل ادمین (۴ KPI + بدهی‌های ارزی + سفارش‌ها و تراکنش‌ها) +- [x] سیستم اعتبار چندارزی کامل (درخواست ۹) — بدهی به همان ارز، تسویه با نرخ روز +- [x] ویجت هشدار بدهی‌های ارزی تسویه‌نشده + badge روی منو +- [x] Rate Limiting روی همهٔ APIها (۶ لایه throttle: auth / sms / public / customer / wallet / staff) +- [x] چک‌لیست خودکار کارمند پس از تأیید سفارش (درخواست ۵) +- [x] نمایش بدهی ارزی در پورتال مشتری وردپرس +- [x] استایل‌دهی صفحهٔ پروفایل مشتری در وردپرس +- [x] پاک‌سازی کد (حذف فایل‌های تستی، تأیید تمیزی `opcache_reset` / `dd` / `dump`) -✅ فلوی کامل سفارش (ثبت → تأیید → تعهدنامه → پرداخت) E2E تست شد -✅ بازطراحی داشبورد + لاگین Filament (navy+amber brand identity) -✅ بازطراحی AWB + Invoice + Label PDF (dompdf, table-based) -✅ صفحه «وضعیت مالی مشتری» در پنل ادمین (۴ KPI + بدهی‌های ارزی + سفارشات/تراکنش‌ها) -✅ سیستم اعتبار چندارزی کامل (درخواست ۹) — بدهی به همان ارز، تسویه با نرخ روز -✅ ویجت هشدار بدهی‌های ارزی تسویه‌نشده + badge روی منو -✅ Rate Limiting روی همه APIها (۶ لایه: auth/sms/public/customer/wallet/staff) -✅ چک‌لیست خودکار کارمند بعد از تأیید سفارش (درخواست ۵) -✅ نمایش بدهی ارزی در پورتال مشتری وردپرس -✅ استایل‌دهی صفحه پروفایل مشتری در وردپرس -✅ پاک‌سازی کد (حذف فایل‌های تستی، تأیید تمیزی opcache_reset/dd/dump) چندزبانه (i18n) همچنان به زمان دیپلوی موکول است. --- -## 🧰 تکنولوژی‌ها و نسخه‌ها +## ۲. تکنولوژی‌ها و نسخه‌ها | لایه | تکنولوژی | نسخه / توضیح | |------|-----------|--------------| -| **Backend** | Laravel | 11.x | -| **PHP** | PHP | ^8.2 (۸.۳ نیز پشتیبانی می‌شود) | -| **Admin Panel** | Filament | 3.3.x | -| **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، فاکتور واردات | -| **SMS** | Kavenegar | تأیید موبایل + اعلان وضعیت سفارش | -| **Excel** | maatwebsite/excel | Import/Export نرخ‌ها و داده‌های تاریخی | -| **Date/Time** | morilog/jalali + Carbon | تاریخ شمسی در نمایش، میلادی در DB | -| **Database** | MySQL | 8.0+ (تست‌ها با SQLite) | -| **Queue** | Redis (ترجیح) / Database | برای پردازش‌های سنگین | -| **Server** | HestiaCP + Nginx + PHP-FPM | تولید (api.ifnex.vernahost.ir) | +| Backend | Laravel | 11.x | +| زبان | PHP | ^8.2 (۸.۳ نیز پشتیبانی می‌شود) | +| پنل مدیریت | Filament | 3.3.x | +| فرانت‌اند | WordPress | 7.x + قالب سفارشی IFNEX | +| احراز هویت | Laravel Sanctum + Bridge Auth | بدون رمز عبور (کلید API مشترک) | +| پرداخت | Zarinpal + Mock Gateway (تست) | کلید sandbox برای تست لوکال | +| PDF و بارکد | Dompdf + picqer/php-barcode-generator | AWB، Invoice، Label، فاکتور واردات | +| پیامک | Kavenegar | تأیید موبایل + اعلان وضعیت سفارش | +| اکسل | maatwebsite/excel | Import / Export نرخ‌ها و داده‌های تاریخی | +| تاریخ و زمان | morilog/jalali + Carbon | تاریخ شمسی در نمایش، میلادی در DB | +| دیتابیس | MySQL | 8.0+ (تست‌ها با SQLite) | +| صف | Redis (ترجیحی) / Database | برای پردازش‌های سنگین | +| سرور | HestiaCP + Nginx + PHP-FPM | تولید (api.ifnex.vernahost.ir) | --- -## 📂 ساختار دایرکتوری (کلیدی) +## ۳. ساختار دایرکتوری -``` +```text IFNEX-Logistics/ -├── 01_Documents/ # مستندات فنی (تحلیل اکسل، نقشه راه، چک‌لیست، ...) -├── 03_WordPress/ # فرانت‌اند وردپرس -│ ├── wp-content/themes/ifnex/ # قالب سفارشی -│ └── wp-content/plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول -├── 04_Laravel/ # بک‌اند لاراول (هسته اصلی) +├── 01_Documents/ # مستندات فنی +│ ├── IFNEX_File_Map.md # نقشهٔ ۱۰۰+ فایل پروژه +│ ├── IFNEX_Roadmap.md # نقشهٔ راه فازی +│ ├── IFNEX_Phase0_Checklist.md # چک‌لیست تکمیل فازها +│ ├── IFNEX_ADR.md # تصمیمات معماری (ADR-001 تا 009) +│ ├── EXCEL_ANALYSIS.md # تحلیل داده‌های تاریخی +│ ├── IFNEX_I18N_Strategy.md # استراتژی چندزبانه +│ └── IFNEX_Commercial_Model.md # مدل تجاری +│ +├── 03_WordPress/ # فرانت‌اند وردپرس +│ └── wp-content/ +│ ├── themes/ifnex/ # قالب سفارشی +│ └── plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول +│ ├── includes/ # api-client، user-bridge، shortcodes، tracking-form +│ └── assets/ # CSS و JS فرم سفارش +│ +├── 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 # همین سند -├── CLIENT_DELIVERY.md # چک‌لیست وضعیت تحویل مشتری (منبع اصلی وضعیت تحویل) -├── DEPLOYMENT.md # راهنمای استقرار در سرور -└── README.md # معرفی کلی پروژه +│ │ ├── Enums/ # ShipmentStatus، ShipmentDirection، ShipmentType، PaymentGateway، TransactionStatus +│ │ ├── Filament/ # ۱۷ Resource + Pages + Widgets +│ │ ├── Http/ +│ │ │ ├── Controllers/Api/ # Track، Pricing، Auth، Bridge، Customer، Wallet، Payment، Staff، CommitmentForm +│ │ │ └── Middleware/ # ApiKeyMiddleware +│ │ ├── Models/ # ۲۶ مدل Eloquent +│ │ ├── Notifications/ # DB notifications + SMS +│ │ ├── Observers/ # ShipmentObserver +│ │ ├── Services/ # PriceCalculator، Pdf، Tracking، OrderPayment، Wallet، Zarinpal، KavenegarSms +│ │ ├── Traits/ # Auditable +│ │ ├── Imports/ # OldShipments، ShippingRates +│ │ └── Exports/ # ShippingRatesTemplateExport +│ ├── database/migrations/ # ۵۲ migration +│ ├── resources/views/pdfs/ # awb، invoice، label، import-invoice +│ └── routes/api.php # ۴۰+ endpoint +│ +├── AGENT.md # همین سند +├── CLIENT_DELIVERY.md # چک‌لیست وضعیت تحویل مشتری (منبع اصلی) +├── DEPLOYMENT.md # راهنمای استقرار روی سرور +├── DEPLOYMENT_HANDOFF.md # تحویل استقرار به تیم IT کارفرما +└── README.md # معرفی کلی پروژه ``` --- -## 🔑 مفاهیم کلیدی بیزینس +## ۴. مفاهیم کلیدی بیزینس -### ۱. مرسوله (Shipment) -- **انواع (Type):** `DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL` -- **جهت (Direction):** `export` (صادرات) و `import` (واردات) -- **وضعیت (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`). +### ۴.۱ مرسوله (Shipment) + +| مورد | مقدار | +|------|-------| +| انواع (`Type`) | `DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL` | +| جهت (`Direction`) | `export` (صادرات) و `import` (واردات) | +| وضعیت (`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) -### ۲. بسته (Package) - هر مرسوله می‌تواند چندین بسته داشته باشد (جدول `shipment_packages`). - وزن حجمی = `(Length × Width × Height) / 5000` (استاندارد IATA). -- وزن قابل پرداخت = `max(وزن واقعی, وزن حجمی)`. +- وزن قابل پرداخت = `max(وزن واقعی، وزن حجمی)`. + +### ۴.۳ فاکتور گمرکی (Invoice) -### ۳. فاکتور گمرکی (Invoice) - فقط برای مرسوله‌های نوع `PARCEL` صادر می‌شود. - حداکثر ۹ قلم کالا (شرح، HS Code، تعداد، قیمت واحد، مجموع به USD). - مجموع کل فاکتور در `shipments.invoice_total_usd` ذخیره می‌شود. -- **فاکتور واردات (Import Invoice):** فیلدهای brand_fee, report_fee, customs_clearance_cost, order_registration_fee و... + قالب PDF مطابق شیت ENG Invoice. +- **فاکتور واردات (Import Invoice):** فیلدهای brand_fee، report_fee، customs_clearance_cost، order_registration_fee و… به‌همراه قالب PDF مطابق شیت ENG Invoice. + +### ۴.۴ کیف پول (Wallet) -### ۴. کیف پول (Wallet) - هر کاربر یک کیف پول دارد. -- تراکنش‌ها (`WalletTransaction`) با نوع `deposit`، `order_payment`، `refund`، `withdrawal` — به‌صورت polymorphic به Payment/سفارش متصل است. -- پرداخت از کیف پول یا درگاه Zarinpal (با Mock برای تست). freeze/unfreeze + activity log کامل. +- تراکنش‌ها (`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 (معتبر ۳۰ روز) و اطلاعات کاربر است. +### ۴.۵ احراز هویت Bridge + +- کاربران وردپرس بدون نیاز به رمز عبور از طریق `POST /api/v1/bridge/login` با ارسال `bridge_api_key` و `wp_user_id` وارد لاراول می‌شوند. +- پاسخ شامل توکن Sanctum (معتبر ۳۰ روز) و اطلاعات کاربر است. - کلید `IFNEX_BRIDGE_API_KEY` باید در هر دو طرف (`.env` لاراول و تنظیمات پلاگین وردپرس) یکسان باشد. -- توکن در usermeta کاربر وردپرس (`ifnex_laravel_token`) ذخیره می‌شود و روی 401 خودکار باطل/تجدید می‌شود. +- توکن در usermeta کاربر وردپرس (`ifnex_laravel_token`) ذخیره می‌شود و روی ۴۰۱ خودکار باطل و تجدید می‌شود. -### ۶. رهگیری (Tracking) -- کاربر با شماره AWB جستجو می‌کند. -- سیستم رویدادهای رهگیری را از جدول `shipment_tracking_events` با `source` (manual, api, import, system, customer) نمایش می‌دهد. -- ایمپورت گروهی وضعیت ترکینگ با CSV از پنل (صفحه BulkTrackingImport). +### ۴.۶ رهگیری (Tracking) + +- کاربر با شمارهٔ AWB جستجو می‌کند. +- سیستم رویدادهای رهگیری را از جدول `shipment_tracking_events` با فیلد `source` (manual، api، import، system، customer) نمایش می‌دهد. +- ایمپورت گروهی وضعیت ترکینگ با CSV از پنل (صفحهٔ BulkTrackingImport) انجام می‌شود. + +### ۴.۷ قیمت‌گذاری (Pricing) -### ۷. قیمت‌گذاری (Pricing) - بر اساس ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس. -- فرمول: قیمت پایه (AED) × ضریب سود × نرخ تبدیل به ریال + هزینه‌های جانبی (Packing, Domestic Pickup, ...) + VAT (۹٪). -- محموله‌های بالای ۳۰ کیلوگرم مشمول نرخ ویژه (Spot Rate) هستند و محاسبه آنلاین ندارند. +- فرمول: قیمت پایه (AED) × ضریب سود × نرخ تبدیل به ریال + هزینه‌های جانبی (Packing، Domestic Pickup، …) + مالیات بر ارزش افزوده (۹٪). +- محموله‌های بالای ۳۰ کیلوگرم مشمول نرخ ویژه (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) اثر می‌گذارند. +### ۴.۸ فلوی تأیید سفارش (Approval Flow) -### ۹. تعهدنامه و اسناد سفارش (Commitment Forms) -- مدیر فرم‌های تعهدنامه را در فیلمنت (`CommitmentFormResource`) آپلود می‌کند (با direction: export/import/both). -- مشتری در جزئیات سفارش وردپرس، لیست تعهدنامه‌ها را می‌بیند → دانلود/پرینت/امضا → آپلود فایل امضاشده (`POST /orders/{shipment}/commitment-forms/{form}/upload`)؛ ثبت در جدول `shipment_commitment_forms`. -- دانلود AWB / Invoice / Label هم از همین بخش (`/orders/{shipment}/pdf/*`) انجام می‌شود. -- ✅ چک مالکیت اعمال شده: `ShipmentPolicy` + بررسی `user_id` در کنترلرهای PDF/تعهدنامه (کامیت `8cf4075`)؛ دانلود قالب تعهدنامه از route محافظت‌شده با auth (جایگزین asset عمومی) و دانلود ادمین از دیسک secure از طریق روت‌های `admin.commitment-forms.*`. +- مشتری بعد از ثبت سفارش **مستقیم به درگاه نمی‌رود**؛ سفارش با وضعیت `pending_approval` ثبت می‌شود. +- کارمند یا مدیر از پنل فیلمنت (اکشن تأیید در `ShipmentResource`) یا از API (`/staff/orders/{id}/approve|reject`) تأیید می‌کند. +- فقط پس از `approved`، گزینه‌های پرداخت (کیف پول / درگاه) در وردپرس باز می‌شود. پرداخت موفق سفارش را `processed` می‌کند (`PaymentController` در callback با `is_order_payment` در metadata). +- سفارش‌های `approved` پرداخت‌نشده روی مانده حساب کاربر (`account_balance` در پروفایل) اثر می‌گذارند. -### ۱۰. اعلان‌ها و SMS کاوه‌نگار -- تنظیمات از `SystemSetting` خوانده می‌شود (`kavenegar_api_key` + سوییچ هر نوع پیام مثل `kavenegar_send_shipment_approved`). -- نوتیفیکیشن‌ها: `ShipmentApprovedSms`، `ShipmentRejectedSms`، `PaymentSuccessSms`، `TrackingUpdatedSms` + کانال `SmsChannel`. -- تریگر اصلی: `ShipmentObserver` (روی تغییر وضعیت Shipment) و PaymentController (پرداخت موفق). تأیید موبایل: `MobileVerificationController`. +### ۴.۹ تعهدنامه و اسناد سفارش (Commitment Forms) + +- مدیر فرم‌های تعهدنامه را در فیلمنت (`CommitmentFormResource`) با direction (export / import / both) آپلود می‌کند. +- مشتری در جزئیات سفارش وردپرس لیست تعهدنامه‌ها را می‌بیند ← دانلود / چاپ / امضا ← آپلود فایل امضاشده (`POST /orders/{shipment}/commitment-forms/{form}/upload`) که در جدول `shipment_commitment_forms` ثبت می‌شود. +- دانلود AWB، Invoice و Label نیز از همین بخش (`/orders/{shipment}/pdf/*`) انجام می‌شود. +- ✅ چک مالکیت اعمال شده: `ShipmentPolicy` + بررسی `user_id` در کنترلرهای PDF و تعهدنامه (کامیت `8cf4075`). +- دانلود قالب تعهدنامه از route محافظت‌شده با auth (جایگزین asset عمومی) و دانلود ادمین از دیسک secure از طریق روت‌های `admin.commitment-forms.*` انجام می‌شود. + +### ۴.۱۰ اعلان‌ها و 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` می‌نویسند (خراب) و اعتبار در فلوی سفارش/پرداخت هم استفاده نشده. -- نیاز کارفرما: بدهی به **ارز سفارش** (مثلاً ۵۰ یورو بدهکار) + تسویه ریالی با نرخ روز → نیاز به بازطراحی دارد. +### ۴.۱۱ اعتبار مشتری (Credit) — چندارزی -### ۱۲. Audit Log -- trait `App\Traits\Auditable` روی مدل‌های اصلی (User, Shipment, Wallet, ...) اعمال شده و در `AuditLogResource` قابل مشاهده است. -- `ShipmentStatusHistory` با ستون‌های `from_status/to_status/reason` + ثبت نام کاربر تغییردهنده. +- سیستم کامل با `CustomerCreditService` (متدهای `grantCredit()`، `settle()`، `getCustomerDebtsByCurrency()`) و جدول‌های `customer_credits` و `credit_settlements` پیاده‌سازی شده است. +- بدهی به همان ارز ثبت می‌شود و تسویه با نرخ روز انجام می‌گیرد. race condition در `settle()` با `lockForUpdate()` و بررسی مجدد مانده اصلاح شد. +- فقط `super_admin` مجاز به اعطای اعتبار است (Policy). + +### ۴.۱۲ Audit Log + +- trait `App\Traits\Auditable` روی مدل‌های اصلی (User، Shipment، Wallet و…) اعمال شده و در `AuditLogResource` قابل مشاهده است. +- `ShipmentStatusHistory` دارای ستون‌های `from_status` / `to_status` / `reason` به‌همراه نام کاربر تغییردهنده است. --- -## ⚙️ دستورات روزمره (برای ایجنت) +## ۵. دستورات روزمره ```bash # نصب وابستگی‌ها @@ -156,34 +199,36 @@ php artisan db:seed --force # اجرای سرور توسعه php artisan serve -# اجرای Queue (برای پردازش‌های سنگین) +# اجرای صف (پردازش‌های سنگین) php artisan queue:work # تست‌ها php artisan test -# پاک‌سازی کش +# پاک‌سازی و بازسازی کش php artisan optimize:clear php artisan config:cache php artisan route:cache php artisan view:cache php artisan filament:clear-cached-components -# ایمپورت/اکسپورت نرخ‌ها +# ایمپورت / اکسپورت نرخ‌ها php artisan ifnex:import:rates {path} php artisan ifnex:import:shipments {path} php artisan ifnex:import:tracking {path} -# بروزرسانی نرخ ارز (کرون) +# به‌روزرسانی نرخ ارز (کرون) php artisan ifnex:update-rates --source=ecb # تولید API Token برای ادمین php artisan ifnex:token ``` -## 🧪 متغیرهای محیطی کلیدی (.env) +--- -```env +## ۶. متغیرهای محیطی کلیدی (`.env`) + +```dotenv APP_ENV=local APP_DEBUG=true APP_URL=http://localhost:8000 @@ -197,7 +242,7 @@ DB_PASSWORD= # IFNEX اختصاصی IFNEX_API_KEY=ifnex-local-dev-key -IFNEX_BRIDGE_API_KEY=ifnex-bridge-secret-key-2026-vernasoft # باید با وردپرس یکی باشد +IFNEX_BRIDGE_API_KEY=ifnex-bridge-secret-key-2026-vernasoft # باید با وردپرس یکی باشد IFNEX_TRACKING_RATE_LIMIT=60 # CORS (فقط دامنه‌های مجاز وردپرس) @@ -220,76 +265,90 @@ 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) | همیشه انگلیسی (برای حمل بین‌المللی) | +| استفاده از ۲ نوع سرویس | ۳ نوع (`DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL`) | +| ذخیرهٔ تاریخ شمسی در DB | ذخیرهٔ timestamp میلادی + تبدیل در نمایش | +| `CORS *` در Production | CORS محدود به دامنهٔ وردپرس | +| کامیت `.env` در Git | قرار دادن `.env` در `.gitignore` | +| `APP_DEBUG=true` در Production | `APP_DEBUG=false` | +| PDF فارسی (AWB / Invoice / Label) | همیشه انگلیسی (برای حمل بین‌المللی) | | کپی از DHL | طراحی منحصر به فرد IFNEX | -| استفاده از wire:click برای دانلود | استفاده از `` با روت مستقیم | -| getFormActions() در Custom Pages | استفاده از wire:click در Blade | -| هدایت AJAX به redirect() | استفاده از payment_url در response JSON | -| متدهای نوتیفیکیشن بیرون از کلاس | داخل کلاس IFNEX_User_Bridge | -| روت staff/admin بدون چک نقش | چک نقش/مالکیت در middleware یا ابتدای کنترلر | -| سفارش مستقیم به درگاه بعد از ثبت | فلوی pending_approval → approved → پرداخت | - -## 📌 نکات ویژه برای ایجنت - -- هنگام تولید کد جدید، حتماً از 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-10-04) -# کار وضعیت -1 تست انتهای فلوی سفارش: آپلود تعهدنامه → تأیید کارمند → پرداخت کیف پول/درگاه ✅ انجام شد (2026-10-04) — فلوی کامل E2E تأیید شد -2 امنیت: چک نقش /staff/* ✅، چک مالکیت PDF/تعهدنامه ✅، محدودسازی discount-codes ✅، rate limiting ✅ (۶ لایه throttle) ✅ انجام شد (2026-10-04) -3 بازطراحی سیستم اعتبار (بدهی چندارزی) + نمایش در پورتال مشتری + ویجت هشدار داشبورد ✅ انجام شد (2026-10-04) — CustomerCreditService کامل + race condition اصلاح شد -4 چک‌لیست خودکار کارمند بعد از تأیید سفارش ✅ انجام شد — instantiateChecklist() در approve() صدا زده می‌شود -5 سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) ⏳ موکول به آینده -6 پاک‌سازی: فایل‌های تستی، cache-busterها، !important ها ✅ انجام شد (2026-10-04) — test_pdf_generation.php حذف شد؛ opcache_reset/dd() پاک؛ !important‌ها ضروری و نگه‌داشته شدند -7 نمایش وزن واقعی/حجمی در خلاصه قیمت وردپرس ✅ در API موجود است (weight + volumetric_weight در پاسخ) -8 چندزبانه (i18n) — به زمان دیپلوی موکول شده ⏳ دیپلوی -وضعیت کلی فاز ۳.۶: ~۹۵٪ تکمیل. تنها موارد باقی‌مانده: i18n (زمان دیپلوی) + سند پیشنهادی مالی (آینده). - - +| استفاده از `wire:click` برای دانلود | استفاده از `` با روت مستقیم | +| `getFormActions()` در Custom Pages | استفاده از `wire:click` در Blade | +| هدایت AJAX به `redirect()` | استفاده از `payment_url` در response JSON | +| متدهای نوتیفیکیشن بیرون از کلاس | داخل کلاس `IFNEX_User_Bridge` | +| روت staff/admin بدون چک نقش | چک نقش یا مالکیت در middleware یا ابتدای کنترلر | +| هدایت مستقیم سفارش به درگاه پس از ثبت | فلوی `pending_approval` ← `approved` ← پرداخت | --- -## 📚 مستندات مرجع (برای مطالعه بیشتر) +## ۸. نکات ویژه برای ایجنت + +### اصول کلی + +- هنگام تولید کد جدید، حتماً از Enum‌ها به‌جای رشته‌های سخت‌کدشده استفاده کن. +- برای هر مدل جدید، migration، مدل و در صورت نیاز کنترلر یا Resource فیلمنت بساز. +- هنگام استفاده از هر Model در فایل جدید، حتماً `use App\Models\...` را import کن. (باگ اخیر نبودِ import برای `SystemSetting` در `PaymentController` / `ShipmentObserver` / `TrackingService`، فلوی تأیید و پرداخت را می‌شکست — کامیت `2737e26`). +- مدیریت تاریخ همیشه با Carbon انجام می‌شود و ذخیره به‌صورت `Y-m-d H:i:s` در DB است. +- برای کوئری‌های سنگین از `chunk()` یا `cursor()` استفاده کن تا حافظه مصرف نشود. + +### خطاهای رایج + +- نبودِ فیلد `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 استفاده کن. + +### هشدارهای تاریخی + +- **مارک‌آپ شورت‌کدهای وردپرس:** باز و بسته بودن `div`ها را متوازن نگه دار. باگ «مرحلهٔ ۲ فرم سفارش لود نمی‌شود» ریشه‌اش یک `div` بسته‌نشده در `shortcodes.php` بود که مراحل را داخل هم nest می‌کرد. هک‌های MutationObserver و setInterval هیچ‌کدام مشکل را حل نکردند و حذف شدند. +- **هک‌های موقت دیباگ:** `opcache_reset()` و `header()` در بالای فایل‌های پلاگین و cache-buster با `time()` فقط برای کار لوکال هستند و باید پیش از دیپلوی حذف شوند. + +--- + +## ۹. کارهای باقی‌مانده (فاز ۳.۶) + +| # | کار | وضعیت | +|---|-----|--------| +| ۱ | تست انتهای فلوی سفارش: آپلود تعهدنامه ← تأیید کارمند ← پرداخت کیف پول یا درگاه | ✅ انجام شد (۲۰۲۶-۱۰-۰۴) | +| ۲ | امنیت: چک نقش `/staff/*`، چک مالکیت PDF و تعهدنامه، محدودسازی discount-codes، rate limiting | ✅ انجام شد (۲۰۲۶-۱۰-۰۴) | +| ۳ | بازطراحی سیستم اعتبار چندارزی + نمایش در پورتال مشتری + ویجت هشدار داشبورد | ✅ انجام شد (۲۰۲۶-۱۰-۰۴) | +| ۴ | چک‌لیست خودکار کارمند پس از تأیید سفارش | ✅ انجام شد (`instantiateChecklist()` در `approve()`) | +| ۵ | سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) | ⏳ موکول به آینده | +| ۶ | پاک‌سازی: فایل‌های تستی، cache-busterها، `!important`ها | ✅ انجام شد (۲۰۲۶-۱۰-۰۴) | +| ۷ | نمایش وزن واقعی و حجمی در خلاصهٔ قیمت وردپرس | ✅ در API موجود است (`weight` + `volumetric_weight` در پاسخ) | +| ۸ | چندزبانه (i18n) | ⏳ موکول به زمان دیپلوی | + +**وضعیت کلی فاز ۳.۶:** حدود ۹۵٪ تکمیل. تنها موارد باقی‌مانده: i18n (زمان دیپلوی) و سند پیشنهادی مالی (آینده). + +--- + +## ۱۰. مستندات مرجع | فایل | محتوا | |------|-------| -| 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-10-04 -نسخه: 1.3 -تهیه‌کننده: VernaSoft Group — Kazem Alghasi +| `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` | راهنمای کامل استقرار روی سرور | +| `DEPLOYMENT_HANDOFF.md` | تحویل استقرار به تیم IT کارفرما | +| `04_Laravel/README.md` | راهنمای بک‌اند | +| `CLIENT_DELIVERY.md` | چک‌لیست وضعیت تحویل مشتری (منبع اصلی وضعیت تحویل) | diff --git a/CLIENT_DELIVERY.md b/CLIENT_DELIVERY.md index 7a3884d..5f0b1bc 100644 --- a/CLIENT_DELIVERY.md +++ b/CLIENT_DELIVERY.md @@ -1,534 +1,533 @@ -# IFNEX — Client Delivery Checklist +# IFNEX — چک‌لیست تحویل به مشتری -> وضعیت تحویل نسخه فعلی IFNEX به مشتری -> این فایل فقط برای مدیریت تعهدات، تست و تحویل نسخه فعلی مشتری است و جایگزین `AGENT.md` یا `IFNEX_Roadmap.md` نیست. +> **وضعیت:** آماده برای دیپلوی (۹۵٪ تکمیل) +> **فاز جاری:** فاز ۳.۶ — اصلاحات جلسهٔ کارفرما +> **تاریخ آخرین به‌روزرسانی:** ۲۰۲۶-۱۰-۰۴ +> **مخزن:** [git.vernahost.ir/gitmodir110/ifnex](https://www.git.vernahost.ir/gitmodir110/ifnex) + +> ⚠️ این فایل فقط برای مدیریت تعهدات، تست و تحویل نسخهٔ فعلی مشتری است و جایگزین `AGENT.md` یا `IFNEX_Roadmap.md` نیست. --- -## 1. Current Delivery Status +## راهنمای وضعیت‌ها -**Project:** IFNEX Logistics Management System -**Current Phase:** Phase 3.6 — Client Meeting Adjustments -**Target:** Production Delivery to Current Client - -### Status Legend - -* ✅ Completed -* 🟡 Implemented — Needs Final Verification -* ⏳ Pending -* 🔴 Blocked -* ❌ Not Implemented +| نشان | معنی | +|------|------| +| ✅ | تکمیل‌شده | +| 🟡 | پیاده‌سازی‌شده — نیازمند تأیید نهایی | +| ⏳ | در انتظار | +| 🔴 | مسدود | +| ❌ | پیاده‌سازی‌نشده | --- -# 2. Client Requested Features +# ۱. فرانت‌اند و صفحهٔ اصلی -## 2.1 Frontend / Landing Page +## ۱.۱ هدایت دکمهٔ ردیابی مرسوله -### Hero Tracking Redirect +**الزام مشتری:** در بخش Hero صفحهٔ اصلی وردپرس، دکمهٔ «ردیابی مرسوله» کاربر را به صفحهٔ اختصاصی Tracking هدایت کند. -**Requirement:** -در بخش Hero صفحه اصلی WordPress، گزینه «ردیابی مرسوله» باید کاربر را به صفحه اختصاصی Tracking هدایت کند. +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی | +| فایل‌ها | `03_WordPress/wp-content/themes/ifnex/`
`03_WordPress/wp-content/plugins/ifnex-bridge/` | -**Status:** 🟡 Implemented — Needs Final Verification +**تست پذیرش:** -**Files to Review:** - -* `03_WordPress/wp-content/themes/ifnex/...` -* `03_WordPress/wp-content/plugins/ifnex-bridge/...` - -**Acceptance Test:** - -* [ ] کلیک روی CTA -* [ ] Redirect صحیح -* [ ] URL صحیح -* [ ] نمایش صحیح صفحه Tracking -* [ ] تست در حالت Login / Guest در صورت نیاز +- [ ] کلیک روی دکمهٔ CTA +- [ ] ریدایرکت صحیح انجام می‌شود +- [ ] URL مقصد صحیح است +- [ ] صفحهٔ Tracking درست نمایش داده می‌شود +- [ ] رفتار در حالت Login و Guest بررسی شد --- -## 2.2 New Order — Multi-Step Form +## ۱.۲ فرم ثبت سفارش چندمرحله‌ای -### Step 1 → Step 2 +**الزام مشتری:** پس از تکمیل مرحلهٔ اول، مرحلهٔ دوم بدون خطا Load شود. -**Requirement:** -پس از تکمیل مرحله اول فرم ثبت سفارش، مرحله دوم بدون خطا Load شود. +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی | +| باگ تاریخی | بسته‌نبودن یک `div` در فایل `shortcodes.php` | +| فایل‌ها | `includes/shortcodes.php`
`assets/js/ifnex-order-form.js` | -**Status:** 🟡 Implemented — Needs Final Verification +**تست پذیرش:** -**Known Historical Issue:** -بسته‌نبودن یک `div` در فایل `shortcodes.php`. - -**Relevant Files:** - -* `03_WordPress/wp-content/plugins/ifnex-bridge/includes/shortcodes.php` -* `03_WordPress/wp-content/plugins/ifnex-bridge/assets/js/ifnex-order-form.js` - -**Acceptance Test:** - -* [ ] Export -* [ ] Import -* [ ] تغییر بین مراحل -* [ ] Validation -* [ ] Browser Console بدون Error -* [ ] حفظ اطلاعات مراحل قبلی +- [ ] حرکت رو به جلو بین مراحل +- [ ] حرکت رو به عقب بین مراحل +- [ ] اعتبارسنجی فرم در هر مرحله +- [ ] حفظ اطلاعات مراحل قبلی +- [ ] Console مرورگر بدون Error +- [ ] رفتار Export و Import بررسی شد --- -## 3. Customer Dashboard / Financial Status +# ۲. داشبورد مشتری و وضعیت مالی -### 3.1 Customer Balance +## ۲.۱ مانده حساب مشتری -**Requirement:** -در Dashboard مشتری، علاوه بر Wallet Balance و Orders، مانده حساب مشتری نیز نمایش داده شود. +**الزام مشتری:** در داشبورد مشتری، علاوه بر موجودی کیف پول و سفارش‌ها، مانده حساب نیز نمایش داده شود. -فرمول مورد انتظار: +**فرمول مورد انتظار:** -`Available Balance / Account Balance = Wallet Balance - Outstanding Approved Obligations` +```text +Account Balance = Wallet Balance − Outstanding Approved Obligations +``` -**Status:** 🟡 Implemented — Needs Final Verification +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی | -**Acceptance Test:** +**تست پذیرش:** -* [ ] Wallet مثبت -* [ ] بدون بدهی -* [ ] دارای بدهی -* [ ] دارای چند سفارش تأییدشده ولی پرداخت‌نشده -* [ ] نمایش صحیح ارز -* [ ] عدم تبدیل بدهی چندارزی به یک مبلغ ریالی اشتباه +- [ ] کیف پول مثبت +- [ ] مشتری بدون بدهی +- [ ] مشتری دارای بدهی +- [ ] مشتری با چند سفارش تأییدشده ولی پرداخت‌نشده +- [ ] نمایش صحیح ارز +- [ ] بدهی چندارزی به مبلغ ریالی اشتباه تبدیل نمی‌شود --- -## 4. Order Approval Before Payment +# ۳. تأیید سفارش پیش از پرداخت -### 4.1 General Flow +> **الزام اصلی:** مشتری بلافاصله پس از ثبت سفارش نباید وارد درگاه پرداخت شود. -**Required Flow:** +## ۳.۱ فلوی عمومی -`Create Order` -→ `Pending Approval` -→ `Staff Review` -→ `Approved` -→ `Documents / Commitment Verification` -→ `Payment Enabled` -→ `Wallet OR Online Payment` -→ `Paid` -→ `Processed` +```text +Create Order + → Pending Approval + → Staff Review + → Approved + → Documents / Commitment Verification + → Payment Enabled + → Wallet OR Online Payment + → Paid + → Processed +``` -**Requirement:** -مشتری بلافاصله پس از ثبت سفارش نباید وارد درگاه شود. +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید End-to-End | -**Status:** 🟡 Implemented — Needs End-to-End Verification +## ۳.۲ سفارش Export + +```text +Create Export Order + → Pending Approval + → Staff Approval + → Documents Available + → Customer Downloads Documents + → Customer Signs / Fingerprints + → Customer Uploads Signed Documents + → Staff Verification + → Payment Enabled + → Wallet / Online Payment + → Paid + → Shipment Processing +``` + +**اسناد مرتبط:** AWB، Invoice، Label، فرم‌های تعهدنامه و سایر اسناد الزامی. + +| مورد | مقدار | +|------|-------| +| وضعیت | ✅ تکمیل — تست End-to-End تأیید شد | + +**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۳):** + +- چرخهٔ تعهدنامه به‌صورت کامل تست شد: دانلود قالب توسط مشتری (از طریق پروکسی وردپرس با توکن)، آپلود فایل امضاشده، تأیید یا رد توسط ادمین در Filament به‌همراه اعلان دیتابیسی، و نمایش وضعیت (تأییدشده / ردشده + دلیل رد) در پورتال مشتری. +- دانلود امن فایل‌ها در پنل ادمین از طریق روت‌های `admin.commitment-forms.*` و از دیسک secure انجام می‌شود. + +**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):** + +- فلوی کامل سفارش (ثبت ← تأیید ← آپلود تعهدنامه ← تأیید تعهدنامه ← پرداخت کیف پول یا درگاه) به‌صورت End-to-End تست و تأیید شد. + +## ۳.۳ سفارش Import + +```text +Create Import Order + → Pending Approval + → Staff Review + → Required Documents + → Customer Verification / Upload + → Staff Verification + → Payment Enabled + → Wallet / Online Payment + → Paid + → Shipment Processing +``` + +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی | --- -### 4.2 Export Order +# ۴. چک‌لیست کارمند -**Required Flow:** +**الزام مشتری:** برای هر سفارش یک چک‌لیست عملیاتی وجود داشته باشد. -`Create Export Order` -→ `Pending Approval` -→ `Staff Approval` -→ `Documents Available` -→ `Customer Downloads Documents` -→ `Customer Signs / Fingerprints` -→ `Customer Uploads Signed Documents` -→ `Staff Verification` -→ `Payment Enabled` -→ `Wallet / Online Payment` -→ `Paid` -→ `Shipment Processing` +**فیلدهای اجباری هر آیتم:** -**Documents:** +| فیلد | +|------| +| عنوان آیتم | +| وضعیت | +| Required / Optional | +| کارمند تکمیل‌کننده | +| تاریخ و ساعت تکمیل | +| یادداشت | +| پیوست (در صورت نیاز) | -* AWB -* Invoice -* Label -* Commitment Forms -* Other required documents +**الزامات مدیر:** -Status: ✅ Implemented — End-to-End Verified +- مشاهدهٔ تمام مراحل +- مشاهدهٔ کارمند انجام‌دهنده +- مشاهدهٔ تاریخ و ساعت +- مشاهدهٔ موارد ناقص +- امکان گزارش‌گیری -🔧 به‌روزرسانی 2026-10-03: چرخه تعهدنامه به‌صورت End-to-End تست و تأیید شد —دانلود قالب توسط مشتری (پروکسی وردپرس با توکن)، آپلود فایل امضاشده، تأیید/رد توسط ادمین در Filamentهمراه با اعلان دیتابیسی به مشتری، و نمایش وضعیت (تأیید شده / رد شده + دلیل رد) در پورتال مشتری.دانلود امن فایل‌ها در پنل ادمین از طریق روت‌های admin.commitment-forms.* از دیسک secure انجام می‌شود. - -✅ به‌روزرسانی 2026-10-04: فلوی کامل سفارش (ثبت → تأیید → آپلود تعهدنامه → تأیید تعهدنامه →پرداخت کیف پول / درگاه) به‌صورت End-to-End تست و تأیید شد. +| مورد | مقدار | +|------|-------| +| وضعیت | ✅ تکمیل — نمونه‌سازی خودکار پس از تأیید | +**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):** +- چک‌لیست پس از تأیید سفارش (در `ShipmentReviewService::approve`) از قالب‌های فعال (`ShipmentChecklistTemplate`) نمونه‌سازی می‌شود. +- مدیریت کامل در `ChecklistsRelationManager` روی `ShipmentResource` و `ShipmentChecklistResource` انجام می‌شود. +- اکشن‌های تکمیل تکی و گروهی به‌همراه فیلدهای `completed_by` و `completed_at` پیاده‌سازی شدند. --- -### 4.3 Import Order +# ۵. تاریخچه و تایم‌لاین مرسوله -**Required Flow:** +**الزام مشتری:** مدیر بتواند تاریخچهٔ کامل هر مرسوله را از ابتدا تا انتها مشاهده کند. -`Create Import Order` -→ `Pending Approval` -→ `Staff Review` -→ `Required Documents` -→ `Customer Verification / Upload` -→ `Staff Verification` -→ `Payment Enabled` -→ `Wallet / Online Payment` -→ `Paid` -→ `Shipment Processing` +هر تغییر وضعیت باید شامل موارد زیر باشد: -**Status:** 🟡 Implemented — Needs Final Verification +- وضعیت قبلی +- وضعیت جدید +- کاربر / کارمند +- تاریخ +- ساعت +- یادداشت + +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی | --- -## 5. Employee Checklist -Requirement:برای هر سفارش یک Checklist عملیاتی وجود داشته باشد. +# ۶. اسناد PDF -هر Checklist Item باید حداقل شامل موارد زیر باشد: +**الزام مشتری:** اسناد AWB، Invoice، Label، فاکتور واردات و تعهدنامه‌ها تولید شوند و طراحی آن‌ها تا حد امکان مطابق نمونه‌های اکسل و اسناد کارفرما باشد. -Item -Status -Required / Optional -Completed By -Completed At -Note -Attachment (when needed) -Manager Requirements: +> **توجه:** تطبیق ۱۰۰٪ پیکسلی به دلیل تفاوت موتور PDF با اکسل ممکن نیست. هدف، نزدیک‌ترین تطبیق عملی و قابل چاپ است. -مشاهده تمام مراحل -مشاهده کارمند انجام‌دهنده -مشاهده تاریخ و ساعت -مشاهده موارد ناقص -امکان گزارش‌گیری +## ۶.۱ بازطراحی انجام‌شده (۲۰۲۶-۱۰-۰۴) -Status: ✅ Implemented — Auto-Instantiated on Approval +| سند | طراحی | +|------|-------| +| AWB | A4 افقی، پالت navy + amber، چیدمان جدولی، بارکد در هدر، لوگوی IFNEX، گرید ۴×۱ | +| Invoice | A4 عمودی، طراحی هم‌سبک AWB، فیلدهای خالی با `@if` مخفی، جدول با راه‌راه Zebra | +| Import Invoice | A4 عمودی، بر اساس شیت ENG Invoice | +| Label | A5 افقی، بدون برند (white-label)، تک‌رنگ، بارکد بزرگ، جدول وزن و ابعاد | -🔧 به‌روزرسانی 2026-10-04: چک‌لیست به‌صورت خودکار بعد از تأیید سفارش (ShipmentReviewService::approve)از قالب‌های فعال (ShipmentChecklistTemplate) نمونه‌سازی می‌شود.مدیریت کامل در ChecklistsRelationManager روی ShipmentResource + ShipmentChecklistResource.اکشن‌های تکمیل/تکمیل گروهی + فیلد completed_by و completed_at پیاده‌سازی شد. +همهٔ اسناد با **dompdf** و چیدمان **جدولی** (نه flexbox) تولید می‌شوند تا سازگاری کامل و بدون overflow تضمین شود. +## ۶.۲ وضعیت تأیید PDF + +| مورد | وضعیت | +|------|--------| +| AWB | ✅ بازطراحی شد | +| Export Invoice | ✅ بازطراحی شد | +| Import Invoice | ✅ بازطراحی شد — نیازمند تأیید نهایی مشتری | +| Label | ✅ بازطراحی شد | +| بارکد | ✅ Code-128 قابل اسکن | +| چیدمان | ✅ جدولی، بدون overflow | +| تایپوگرافی | ✅ DejaVu Sans / Vazirmatn | +| اندازهٔ صفحه | ✅ A4 افقی (AWB) / A4 عمودی (Invoice) / A5 افقی (Label) | +| خروجی چاپ | ⏳ نیازمند تست چاپ فیزیکی | + +| وضعیت کلی بخش | مقدار | +|----------------|-------| +| نتیجه | 🟡 پیاده‌سازی‌شده — در انتظار تأیید نهایی مشتری | --- -## 6. Shipment History / Timeline +# ۷. اطلاعات مالی مشتری (کارمند / مدیر) -**Requirement:** -مدیر بتواند تاریخچه کامل هر Shipment را از شروع تا پایان مشاهده کند. +**الزام مشتری:** کارمند یا مدیر بتواند با انتخاب یا جستجوی مشتری، اطلاعات مالی کامل او را مشاهده کند. -هر تغییر باید تا حد امکان شامل موارد زیر باشد: +**اطلاعات مورد نیاز:** -* Previous Status -* New Status -* User / Employee -* Date -* Time -* Note +- موجودی فعلی +- مطالبات / بدهی‌ها +- ارز +- تراکنش‌های اخیر +- سفارش‌های اخیر +- شمارهٔ مرجع سفارش +- مبلغ +- وضعیت پرداخت +- تاریخ‌ها +- یادداشت‌ها -**Status:** 🟡 Implemented — Needs Final Verification +| مورد | مقدار | +|------|-------| +| وضعیت | ✅ تکمیل — صفحهٔ نمای کلی مالی مشتری ساخته شد | + +**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):** + +- صفحهٔ «وضعیت مالی مشتری» در `App\Filament\Pages\CustomerFinancialOverview` ساخته شد. +- مدیر یا کارمند با جستجوی مشتری موارد زیر را می‌بیند: + - ۴ کارت KPI: موجودی کیف پول، بدهی فعلی، کل پرداختی، مانده حساب + - جدول بدهی‌های چندارزی به تفکیک ارز (EUR / USD / AED / CNY) + - ۵ سفارش اخیر و ۵ تراکنش اخیر + - دکمه‌های اقدام: اعتبار جدید، سفارش‌ها، وضعیت مالی +- طراحی با گرید ۱۲ ستونی و CSS اختصاصی IFNEX انجام شده است. --- -## 7. PDF Documents +# ۸. اعتبار مشتری (چندارزی) -### Required Documents +**الزام مشتری:** فقط مدیر کل بتواند برای مشتریِ شناخته‌شده اعتبار ایجاد یا افزایش دهد. -* AWB -* Invoice -* Label -* Import Invoice -* Commitment Documents where applicable +## ۸.۱ قاعدهٔ اصلی -**Requirement:** -طراحی PDFها باید تا حد امکان مطابق نمونه‌های Excel / Client Documents باشد. +اگر مشتری مثلاً **۵۰ EUR** بدهکار باشد، بدهی باید به همان ارز ثبت شود و **نباید** به مبلغ ریالی روز تبدیل و جایگزین شود. -**Important:** -تطبیق 100٪ پیکسلی ممکن است به دلیل تفاوت موتور PDF با Excel امکان‌پذیر نباشد. هدف، نزدیک‌ترین تطبیق عملی و قابل چاپ است. +## ۸.۲ اطلاعات لازم هنگام تسویهٔ ریالی -Status: 🟡 Implemented — Awaiting Final Client Approval +| فیلد | +|------| +| مبلغ اصلی | +| ارز اصلی | +| ارز تسویه | +| نرخ تبدیل | +| تاریخ نرخ | +| مبلغ تسویه | +| دلیل / مرجع | -🔧 به‌روزرسانی 2026-10-04: هر سه سند بازطراحی شدند: +| مورد | مقدار | +|------|-------| +| وضعیت | ✅ تکمیل — سیستم اعتبار چندارزی کامل شد | -AWB — A4 عرضی، navy+amber palette، table-based layout، بارکد در هدر، لوگوی IFNEX، گرید ۴×۱ -Invoice — A4 عمودی، طراحی AWB-style، فیلدهای خالی با @if مخفی، zebra stripe جدول -Label — A5 عرضی، بدون برند (white-label)، مونوکروم، بارکد بزرگ، جدول وزن/ابعادتمام سند‌ها با dompdf و table-based layout (نه flexbox) برای سازگاری کامل تولید می‌شوند. -Final PDF Acceptance - AWB — بازطراحی شد ✅ - Export Invoice — بازطراحی شد ✅ - Import Invoice — بازطراحی شد (نیاز به بازبینی نهایی مشتری) - Label — بازطراحی شد ✅ - Barcode — قابل اسکن Code-128 ✅ - Alignment — table-based، بدون overflow ✅ - Typography — DejaVu Sans / Vazirmatn ✅ - Page size — A4 landscape (AWB) / A4 portrait (Invoice) / A5 landscape (Label) ✅ - Printable output — نیاز به تست چاپ فیزیکی +**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):** + +- `CustomerCreditService` با متدهای `grantCredit()`، `settle()` و `getCustomerDebtsByCurrency()` +- جدول‌های `customer_credits` و `credit_settlements` — بدهی به همان ارز ثبت و تسویه با نرخ روز +- `CustomerCreditResource` با فرم ایجاد و اکشن تسویه (`exchange_rate`، `rate_date`، `from_wallet`) +- `CreditsRelationManager` روی `UserResource` برای مشاهدهٔ درجا +- نمایش بدهی‌های ارزی در پورتال مشتری (تب کیف پول و پروفایل در وردپرس) +- ویجت داشبورد «بدهی‌های ارزی تسویه‌نشده» به‌همراه badge روی منو +- اصلاح race condition در `settle()` با بررسی مجدد مانده پس از `lockForUpdate()` +- Policy: فقط `super_admin` مجاز به اعطای اعتبار است --- -## 8. Customer Financial Information — Staff / Manager +# ۹. ایمپورت گروهی وضعیت ترکینگ -**Requirement:** -کارمند یا مدیر بتواند با انتخاب یا جستجوی مشتری، اطلاعات مالی کامل او را مشاهده کند. +**الزام مشتری:** امکان Import گروهی آخرین وضعیت Trackingها در پنل مدیریت. -#### Required Information +| مورد | مقدار | +|------|-------| +| ورودی | فایل CSV یا فرمت Import تأییدشده | +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی | -* Current Balance -* Receivables / Payables -* Currency -* Recent Transactions -* Recent Orders -* Order Reference -* Amount -* Payment Status -* Dates -* Notes - -Status: ✅ Implemented — Customer Financial Overview Page Built - -🔧 به‌روزرسانی 2026-10-04: صفحه «وضعیت مالی مشتری» در پنل ادمین ساخته شد(App\Filament\Pages\CustomerFinancialOverview).مدیر/کارمند با جستجوی مشتری می‌بیند: - -۴ کارت KPI (موجودی کیف پول، بدهی فعلی، کل پرداختی، مانده حساب) -جدول بدهی‌های چندارزی به تفکیک ارز (EUR/USD/AED/CNY) -۵ سفارش اخیر + ۵ تراکنش اخیر -دکمه‌های اقدام (اعتبار جدید، سفارشات، وضعیت مالی)طراحی با گرید ۱۲ ستونی و CSS اختصاصی IFNEX. +**خروجی مورد انتظار:** +- یافتن مرسوله +- اعتبارسنجی شمارهٔ ترکینگ +- به‌روزرسانی وضعیت +- ثبت تاریخچه +- ثبت نتیجهٔ Import +- گزارش ردیف‌های ناموفق --- -## 9. Customer Credit +# ۱۰. ویرایش مدیریتی و Audit Log -**Requirement:** -فقط مدیر کل بتواند برای مشتری شناخته‌شده Credit ایجاد یا افزایش دهد. +**الزام مشتری:** مدیر بتواند تقریباً همهٔ اطلاعات عملیاتی لازم را ویرایش کند. -#### Important Rule +> **قاعدهٔ مهم:** تغییرات مدیریتی باید قابل Audit باشند. -اگر مشتری: +**اطلاعات Audit:** -`50 EUR` +- کاربر +- نوع عملیات +- مدل +- رکورد +- مقدار قبلی +- مقدار جدید +- تاریخ +- ساعت +- IP (در صورت کاربرد) -بدهکار است، بدهی باید به صورت: - -`50 EUR` - -ثبت شود و نباید به مبلغ ریالی روز تبدیل و جایگزین شود. - -هنگام تسویه ریالی: - -* Original Amount -* Original Currency -* Settlement Currency -* Exchange Rate -* Exchange Rate Date -* Settlement Amount -* Reason / Reference - -باید ثبت شود. - -Status: ✅ Implemented — Multi-Currency Credit System Completed - -🔧 به‌روزرسانی 2026-10-04: سیستم اعتبار چندارزی کامل شد: - -CustomerCreditService با متدهای grantCredit() / settle() / getCustomerDebtsByCurrency() -جدول customer_credits + credit_settlements — بدهی به همان ارز ثبت، تسویه با نرخ روز -CustomerCreditResource با فرم ایجاد + اکشن تسویه (exchange_rate, rate_date, from_wallet) -CreditsRelationManager روی UserResource برای دیدن inline -نمایش بدهی‌های ارزی در پورتال مشتری (WP wallet tab + profile) -ویجت داشبورد «بدهی‌های ارزی تسویه‌نشده» + badge روی منو -اصلاح race condition در settle() با بررسی مجدد مانده بعد از lockForUpdate() -Policy: فقط super_admin می‌تواند اعتبار اعطا کند +| مورد | مقدار | +|------|-------| +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند بررسی امنیت و مجوز دسترسی | --- -## 10. Bulk Tracking Import +# ۱۱. یکپارچه‌سازی پیامک -**Requirement:** -امکان Import گروهی آخرین وضعیت Trackingها در پنل مدیریت. +| مورد | مقدار | +|------|-------| +| سرویس‌دهنده | Kavenegar | +| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند پیکربندی Production و تأیید End-to-End | -**Expected Input:** -CSV / approved import format +**موارد استفاده:** -**Expected Result:** - -* Find Shipment -* Validate Tracking Number -* Update Status -* Register History -* Record Import Result -* Report Failed Rows - -**Status:** 🟡 Implemented — Needs Final Verification +- تأیید موبایل +- تأیید ثبت‌نام +- ثبت سفارش +- تأیید سفارش +- رد سفارش +- پرداخت موفق +- تغییر وضعیت ترکینگ +- اعلان‌های مهم سیستم --- -## 11. Admin Editing + Audit Log +# ۱۲. سخت‌سازی Production -**Requirement:** -مدیر بتواند تقریباً همه اطلاعات عملیاتی لازم را ویرایش کند. +## ۱۲.۱ امنیت -**Important Rule:** -تغییرات مدیریتی باید قابل Audit باشند. +| مورد | وضعیت | +|------|--------| +| حذف / چرخش اسکریت‌های افشاشده | ⏳ | +| بررسی نحوهٔ نگهداری Bridge API Key | ⏳ | +| بررسی مجوز روت‌های Staff | ✅ `StaffApiMiddleware` روی همهٔ `/staff/*` | +| بررسی عملیات مختص مدیر | ✅ Policy روی `CustomerCredit` و `Shipment` | +| اعتبارسنجی آپلود فایل | ⏳ | +| بررسی مالکیت و مجوز اسناد | ✅ `ShipmentPolicy` و `CustomerCreditPolicy` | +| امنیت Callback پرداخت | ✅ `OrderPaymentService` با محافظ Mock در Production | +| غیرفعال‌سازی Mock Gateway در Production | ⏳ | +| Rate Limiting | ✅ ۲۰۲۶-۱۰-۰۴ — ۶ لایه throttle: auth / sms / public / customer / wallet / staff | -#### Audit Information +## ۱۲.۲ یکپارچگی مالی -* User -* Action -* Model -* Record -* Old Value -* New Value -* Date -* Time -* IP where applicable +| مورد | وضعیت | +|------|--------| +| حفاظت از همزمانی کیف پول | ✅ `lockForUpdate()` در `CustomerCreditService::settle()` | +| یکتایی پرداخت (Idempotency) | ✅ race condition اصلاح شد | +| منطق مصرف کد تخفیف | ⏳ | +| دقت مبلغ و ارز | ✅ cast با `decimal:2` | +| یکپارچگی بدهی چندارزی | ✅ بدهی به همان ارز ثبت می‌شود، نه معادل ریالی | -**Status:** 🟡 Implemented — Needs Security / Authorization Verification +> ✅ **انجام شد (۲۰۲۶-۱۰-۰۳):** تغییر نرخ ارز فقط از منوی «نرخ ارز» (تاریخچه + گردش تأیید + به‌روزرسانی از API) انجام می‌شود. فیلدهای مستقیم نرخ در «تنظیمات سیستم» حذف و به نمایش فقط‌خواندنی تبدیل شدند. + +## ۱۲.۳ اپلیکیشن + +| مورد | وضعیت | +|------|--------| +| بازبینی فلوی قدیمی سفارش | ⏳ | +| مدیریت خطاها | ⏳ | +| لاگ Production | ⏳ | +| پیکربندی Cache / OPcache | ⏳ | +| نسخه‌بندی Assetها | ⏳ | --- -## 12. SMS Integration +# ۱۳. تست پذیرش End-to-End -**Provider:** Kavenegar +## ۱۳.۱ مشتری -#### Required Use Cases +- [ ] ثبت‌نام +- [ ] تأیید موبایل +- [ ] ورود +- [ ] ثبت سفارش Export +- [ ] ثبت سفارش Import +- [ ] مشاهدهٔ سفارش +- [ ] انتظار برای تأیید +- [ ] دریافت اسناد +- [ ] دانلود اسناد +- [ ] آپلود اسناد امضاشده +- [ ] دریافت تأیید +- [ ] پرداخت با کیف پول +- [ ] پرداخت آنلاین +- [ ] مشاهدهٔ موجودی +- [ ] مشاهدهٔ تراکنش‌ها +- [ ] مشاهدهٔ ترکینگ +- [ ] دریافت اعلان‌ها -* Mobile Verification -* Registration Verification -* Order Submitted -* Order Approved -* Order Rejected -* Payment Successful -* Tracking Status Changes -* Important System Notifications +## ۱۳.۲ کارمند -**Status:** 🟡 Implemented — Needs Production Configuration / End-to-End Verification +- [ ] مشاهدهٔ سفارش‌ها +- [ ] تأیید سفارش +- [ ] رد سفارش +- [ ] آپلود تعهدنامه +- [ ] بررسی اسناد مشتری +- [ ] تکمیل چک‌لیست +- [ ] به‌روزرسانی مرسوله +- [ ] ایمپورت ترکینگ +- [ ] مشاهدهٔ وضعیت مالی مشتری +- [ ] مشاهدهٔ سفارش‌های مشتری +- [ ] بازبینی Audit Log + +## ۱۳.۳ مدیر / مدیر کل + +- [ ] بازبینی مالی مشتری +- [ ] اعطای اعتبار +- [ ] ویرایش اعتبار +- [ ] بازبینی Audit +- [ ] مشاهدهٔ تایم‌لاین مرسوله +- [ ] ویرایش داده‌های عملیاتی +- [ ] بازبینی فعالیت کارمندان --- -# 13. Production Hardening +# ۱۴. دروازهٔ نهایی تحویل -Security - Remove / rotate exposed secrets - Verify Bridge API Key handling - Verify Staff route authorization ✅ (StaffApiMiddleware روی همه /staff/*) - Verify Admin-only operations ✅ (Policy روی CustomerCredit, Shipment) - Verify File Upload validation - Verify document ownership / authorization ✅ (ShipmentPolicy + CustomerCreditPolicy) - Verify payment callback security ✅ (OrderPaymentService با production mock guard) - Disable Mock Gateway in Production - Rate Limiting ✅ (2026-10-04: ۶ لایه throttle — auth/sms/public/customer/wallet/staff) -Financial Integrity - Wallet concurrency protection ✅ (lockForUpdate() در CustomerCreditService::settle()) - Payment idempotency ✅ (race condition اصلاح شد) - Coupon consumption logic - Money / currency precision ✅ (decimal:2 casts) - Multi-currency debt integrity ✅ (بدهی به همان ارز ثبت، نه معادل ریالی) +پیش از انتشار در Production: -> ✅ **انجام شد (2026-10-03):** تغییر نرخ ارز فقط از منوی «نرخ ارز» (تاریخچه + گردش تأیید + آپدیت از API) — فیلدهای مستقیم نرخ در «تنظیمات سیستم» حذف و به نمایش فقط‌خواندنی تبدیل شدند. - -## Application - -* [ ] Legacy Order Flow review -* [ ] Exception handling -* [ ] Production logging -* [ ] Cache / OPcache configuration -* [ ] Asset versioning +- [ ] همهٔ قابلیت‌های الزامی پیاده‌سازی شده‌اند +- [ ] باگ‌های بحرانی برطرف شده‌اند +- [ ] بازبینی امنیتی انجام شده +- [ ] فلوی پرداخت تست شده +- [ ] فلوی کیف پول تست شده +- [ ] فلوی Export تست شده +- [ ] فلوی Import تست شده +- [ ] PDFها تأیید شده‌اند +- [ ] پیامک تست شده +- [ ] ایمپورت ترکینگ تست شده +- [ ] بکاپ بررسی شده +- [ ] محیط Production بررسی شده +- [ ] تست پذیرش کارفرما (UAT) انجام شده --- -# 14. End-to-End Acceptance Testing +# ۱۵. خلاصهٔ وضعیت تحویل -## Customer +**وضعیت فعلی:** آماده برای دیپلوی (۹۵٪ تکمیل) -* [ ] Register -* [ ] Mobile Verification -* [ ] Login -* [ ] Create Export Order -* [ ] Create Import Order -* [ ] View Order -* [ ] Wait for Approval -* [ ] Receive Documents -* [ ] Download Documents -* [ ] Upload Signed Documents -* [ ] Receive Approval -* [ ] Pay with Wallet -* [ ] Pay Online -* [ ] View Balance -* [ ] View Transactions -* [ ] View Tracking -* [ ] Receive Notifications +**آخرین کامیت بازبینی‌شده:** ۲۰۲۶-۱۰-۰۴ — شامل بازطراحی PDF، صفحهٔ وضعیت مالی مشتری، Rate Limiting و سیستم اعتبار چندارزی کامل. -## Staff +## ۱۵.۱ تکمیل‌شده در این دوره -* [ ] View Orders -* [ ] Approve Order -* [ ] Reject Order -* [ ] Upload Commitment -* [ ] Verify Customer Documents -* [ ] Complete Checklist -* [ ] Update Shipment -* [ ] Import Tracking -* [ ] View Customer Financial Status -* [ ] View Customer Orders -* [ ] Review Audit Log +- [x] فلوی پذیرش End-to-End (کیف پول + درگاه پس از تأیید تعهدنامه) +- [x] بازطراحی داشبورد و صفحهٔ Login (پنل Filament) +- [x] بازطراحی PDFهای AWB، Invoice و Label (dompdf، چیدمان جدولی، navy + amber) +- [x] صفحهٔ وضعیت مالی مشتری در پنل ادمین +- [x] سیستم اعتبار چندارزی (درخواست ۹) — تکمیل End-to-End +- [x] ویجت بدهی‌های ارزی تسویه‌نشده + badge ناوبری +- [x] اصلاح race condition در تسویهٔ اعتبار +- [x] `CreditsRelationManager` روی `UserResource` +- [x] Rate Limiting روی همهٔ endpointهای API (۶ لایه) +- [x] چک‌لیست خودکار کارمند پس از تأیید سفارش (درخواست ۵) +- [x] نمایش بدهی ارزی در پورتال مشتری وردپرس +- [x] استایل‌دهی صفحهٔ پروفایل مشتری در وردپرس +- [x] پاک‌سازی کد (حذف فایل‌های تستی، تأیید تمیزی کد) -## Manager / Super Admin +## ۱۵.۲ باقی‌مانده -* [ ] Customer Financial Review -* [ ] Grant Credit -* [ ] Modify Credit -* [ ] Review Audit -* [ ] View Shipment Timeline -* [ ] Edit Operational Data -* [ ] Review Staff Activity +- [ ] i18n (موکول به زمان دیپلوی) +- [ ] تست نهایی UAT کارفرما +- [ ] دیپلوی روی سرور Production +- [ ] سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما — موکول به آینده) --- -# 15. Final Delivery Gate - -Before Production: - -* [ ] All required features implemented -* [ ] All critical bugs fixed -* [ ] Security review completed -* [ ] Payment flow tested -* [ ] Wallet flow tested -* [ ] Export flow tested -* [ ] Import flow tested -* [ ] PDFs approved -* [ ] SMS tested -* [ ] Tracking import tested -* [ ] Backup verified -* [ ] Production environment verified -* [ ] Client UAT completed - ---- - -# 16. Delivery Status -Current Status: READY FOR DEPLOYMENT (95% Complete) - -Completed in This Session: - -✅ E2E Payment Flow (wallet + gateway after commitment verification) -✅ Dashboard + Login redesign (Filament admin panel) -✅ AWB + Invoice + Label PDF redesign (dompdf, table-based, navy+amber) -✅ Customer Financial Overview page (admin panel) -✅ Multi-currency credit system (درخواست ۹) — complete E2E -✅ Unsettled credits dashboard widget + navigation badge -✅ Race condition fix in credit settlement -✅ CreditsRelationManager on UserResource -✅ Rate Limiting on all API endpoints (6 layers) -✅ Auto employee checklist on approval (درخواست ۵) -✅ Foreign currency debts in customer portal (WP) -✅ Profile page styling (WP customer dashboard) -✅ Cleanup (test files removed, code verified clean) -Remaining: - -⏳ i18n (deferred to deployment) -⏳ Final client UAT -⏳ Deployment to production server -Last Reviewed Commit: Latest (2026-10-04 — شامل بازطراحی PDF، صفحه وضعیت مالی مشتری، Rate Limiting، و سیستم اعتبار چندارزی کامل) - -Source Repository: - -`https://www.git.vernahost.ir/gitmodir110/ifnex - - - ---- - -## Notes - -این فایل باید در طول تحویل پروژه به‌روزرسانی شود. - -این فایل برای وضعیت تحویل مشتری است و نباید تبدیل به مستندات معماری یا Roadmap محصول شود. +> **نکتهٔ نگهداری:** این فایل باید در طول تحویل پروژه به‌روزرسانی شود. این فایل فقط برای وضعیت تحویل مشتری است و نباید به مستندات معماری یا Roadmap محصول تبدیل شود. diff --git a/DEPLOYMENT_HANDOFF.md b/DEPLOYMENT_HANDOFF.md new file mode 100644 index 0000000..d71ec7d --- /dev/null +++ b/DEPLOYMENT_HANDOFF.md @@ -0,0 +1,233 @@ +# راهنمای استقرار IFNEX — ویژهٔ تیم IT کارفرما + +> **مخاطب:** مسئول IT شرکت IFNEX +> **تاریخ تحویل:** ۲۰۲۶-۱۰-۰۴ +> **نسخه:** ۱.۰ +> **تهیه‌کننده:** VernaSoft Group — Kazem Alghasi + +--- + +## ۱. معماری استقرار + +این سیستم از دو بخش مستقل تشکیل شده است که هرکدام روی دامنهٔ جداگانه میزبانی می‌شوند و فقط از طریق REST API با هم ارتباط دارند. + +| بخش | دامنه | روش تحویل | مسیر وب‌سرور | +|------|-------|------------|--------------| +| لاراول (API + پنل مدیریت Filament) | `system.ifnex.ir` | کلون گیت | `/var/www/system.ifnex.ir/public` | +| وردپرس (وب‌سایت + پورتال مشتری) | `ifnex.ir` | فایل ZIP + فایل SQL | `/var/www/ifnex.ir` | + +**پیش‌نیازهای هر دو بخش:** + +- PHP 8.2 یا بالاتر با اکستنشن‌های `pdo_mysql`، `mbstring`، `xml`، `gd`، `zip` +- MySQL 8 یا بالاتر +- Composer 2.x (فقط برای لاراول) +- Nginx یا Apache + PHP-FPM +- گواهی SSL از Let's Encrypt برای هر دو دامنه + +--- + +## ۲. استقرار لاراول — `system.ifnex.ir` + +### ۲.۱ کلون مخزن + +```bash +cd /var/www/system.ifnex.ir + +git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git tmp + +cp -r tmp/04_Laravel/* . +cp tmp/04_Laravel/.env.example .env + +rm -rf tmp +``` + +### ۲.۲ نصب پکیج‌ها + +```bash +composer install --no-dev --optimize-autoloader +``` + +### ۲.۳ تنظیم فایل `.env` + +```bash +nano .env +``` + +مقادیر زیر را حتماً تنظیم کنید: + +```dotenv +APP_NAME=IFNEX +APP_ENV=production +APP_DEBUG=false +APP_URL=https://system.ifnex.ir + +DB_CONNECTION=mysql +DB_HOST=127.0.0.1 +DB_PORT=3306 +DB_DATABASE=ifnex_laravel +DB_USERNAME=YOUR_DB_USER +DB_PASSWORD=YOUR_DB_PASSWORD + +IFNEX_BRIDGE_API_KEY=CHANGE_THIS_TO_A_RANDOM_SECRET +CORS_ALLOWED_ORIGINS=https://ifnex.ir + +ZARINPAL_SANDBOX=false +ZARINPAL_MERCHANT_ID=YOUR_REAL_MERCHANT_ID +ZARINPAL_CALLBACK_URL=https://system.ifnex.ir/api/v1/payment/callback +ZARINPAL_FRONTEND_SUCCESS_URL=https://ifnex.ir/wallet +ZARINPAL_FRONTEND_FAILURE_URL=https://ifnex.ir/wallet + +KAVENEGAR_API_KEY=YOUR_KAVENEGAR_KEY +KAVENEGAR_SENDER=YOUR_SENDER_NUMBER +``` + +> ⚠️ **نکتهٔ امنیتی:** مقدار `IFNEX_BRIDGE_API_KEY` را پیش از استقرار با یک کلید تصادفی و طولانی جایگزین کنید. این مقدار باید عیناً در پلاگین وردپرس هم تنظیم شود. + +### ۲.۴ راه‌اندازی اولیه + +```bash +php artisan key:generate +php artisan migrate --force +php artisan storage:link +php artisan config:cache +php artisan route:cache +php artisan view:cache +``` + +تنظیم دسترسی پوشه‌ها: + +```bash +chown -R www-data:www-data storage bootstrap/cache +chmod -R 775 storage bootstrap/cache +``` + +### ۲.۵ تنظیم Cron + +برای اجرای صف و زمان‌بندی‌ها، این خط را در کرون اضافه کنید: + +```cron +* * * * * cd /var/www/system.ifnex.ir && php artisan schedule:run >> /dev/null 2>&1 +``` + +اگر صف با Redis اجرا می‌شود، این خط را نیز اضافه کنید: + +```cron +* * * * * cd /var/www/system.ifnex.ir && php artisan queue:work --tries=3 >> /dev/null 2>&1 +``` + +--- + +## ۳. استقرار وردپرس — `ifnex.ir` + +### ۳.۱ نصب فایل‌ها + +1. فایل ZIP وردپرس را در `/var/www/ifnex.ir` اکسترکت کنید. +2. فایل SQL دیتابیس را ایمپورت کنید. + +### ۳.۲ تنظیم `wp-config.php` + +```php +define('DB_NAME', 'ifnex_wordpress'); +define('DB_USER', 'YOUR_WP_DB_USER'); +define('DB_PASSWORD', 'YOUR_WP_DB_PASSWORD'); +define('DB_HOST', '127.0.0.1'); +define('WP_HOME', 'https://ifnex.ir'); +define('WP_SITEURL', 'https://ifnex.ir'); +``` + +### ۳.۳ فعال‌سازی قالب و پلاگین + +قالب `IFNEX Theme` و پلاگین `IFNEX Bridge` را از بخش افزونه‌های وردپرس فعال کنید. + +### ۳.۴ تنظیمات پلاگین IFNEX Bridge + +از مسیر **پنل وردپرس → تنظیمات IFNEX**: + +| تنظیم | مقدار | +|--------|--------| +| API URL | `https://system.ifnex.ir/api/v1` | +| Bridge API Key | همان مقدار `IFNEX_BRIDGE_API_KEY` در فایل `.env` لاراول | + +### ۳.۵ اصلاح آدرس‌ها در دیتابیس + +اگر سایت از محیط لوکال به سرور منتقل می‌شود، آدرس‌های ذخیره‌شده را اصلاح کنید: + +```sql +UPDATE wp_options + SET option_value = REPLACE(option_value, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir') + WHERE option_name IN ('home', 'siteurl'); + +UPDATE wp_posts + SET guid = REPLACE(guid, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir'); + +UPDATE wp_posts + SET post_content = REPLACE(post_content, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir'); + +UPDATE wp_postmeta + SET meta_value = REPLACE(meta_value, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir'); +``` + +سپس کش وردپرس را پاک کنید (اگر افزونهٔ کش دارید) و یک‌بار به پیشخوان وردپرس بروید. + +--- + +## ۴. تنظیمات وب‌سرور + +### ۴.۱ لاراول — `system.ifnex.ir` + +- **Document Root:** `/var/www/system.ifnex.ir/public` + +### ۴.۲ وردپرس — `ifnex.ir` + +- **Document Root:** `/var/www/ifnex.ir` + +### ۴.۳ گواهی SSL + +هر دو دامنه به گواهی SSL از Let's Encrypt نیاز دارند. پس از نصب گواهی، مطمئن شوید ریدایرکت HTTP به HTTPS فعال است. + +--- + +## ۵. چک‌لیست نهایی + +### ۵.۱ لاراول + +- [ ] کلون مخزن انجام شد +- [ ] `composer install` اجرا شد +- [ ] فایل `.env` تنظیم شد (دیتابیس، `APP_URL`، CORS، Zarinpal، Kavenegar) +- [ ] `php artisan key:generate` اجرا شد +- [ ] `php artisan migrate` اجرا شد +- [ ] `php artisan storage:link` اجرا شد +- [ ] دسترسی `storage/` و `bootstrap/cache/` تنظیم شد +- [ ] `php artisan config:cache` اجرا شد +- [ ] کرون اضافه شد +- [ ] آدرس `https://system.ifnex.ir/panel/login` باز می‌شود + +### ۵.۲ وردپرس + +- [ ] فایل‌ها اکسترکت شدند +- [ ] دیتابیس ایمپورت شد +- [ ] `wp-config.php` تنظیم شد +- [ ] آدرس‌ها در دیتابیس جایگزین شدند +- [ ] قالب و پلاگین IFNEX Bridge فعال شدند +- [ ] پلاگین تنظیم شد (API URL + Bridge API Key) +- [ ] آدرس `https://ifnex.ir` باز می‌شود +- [ ] لاگین مشتری کار می‌کند + +### ۵.۳ ارتباط بین‌سامانه‌ای + +- [ ] وردپرس به API لاراول وصل می‌شود (تست: لاگین مشتری) +- [ ] خطای CORS داده نمی‌شود +- [ ] پرداخت درگاه کار می‌کند (`ZARINPAL_MERCHANT_ID` تنظیم شده و `ZARINPAL_SANDBOX=false`) +- [ ] ارسال پیامک Kavenegar تست شد +- [ ] بارگذاری فایل (آپلود تعهدنامه) کار می‌کند +- [ ] بکاپ دیتابیس تنظیم شده است + +--- + +## ۶. اطلاعات تماس + +| مورد | مقدار | +|------|-------| +| توسعه‌دهنده | VernaSoft Group — Kazem Alghasi | +| ایمیل | kazem@vernasoft.group | +| مخزن گیت | [git.vernahost.ir/gitmodir110/ifnex](https://www.git.vernahost.ir/gitmodir110/ifnex) | diff --git a/README.md b/README.md index 1d594b4..f1b891e 100644 --- a/README.md +++ b/README.md @@ -16,50 +16,47 @@ *جایگزینی فرآیندهای دستی مبتنی بر اکسل با معماری Headless مدرن* -**[📚 مستندات](#-مستندات)** • **[⚡ شروع سریع](#-شروع-سریع)** • **[🏗️ معماری](#%EF%B8%8F-معماری-سیستم)** • **[📞 پشتیبانی](#-تماس)** +**[📚 مستندات](#-مستندات)** • **[⚡ شروع سریع](#-شروع-سریع)** • **[🏗️ معماری](#%EF%B8%8F-معماری-سیستم)** • **[📞 تماس](#-تماس)** --- -## 📖 درباره پروژه +## 📖 دربارهٔ پروژه -**IFNEX** یک راه‌حل جامع برای شرکت‌های حمل‌ونقل بین‌المللی است که فرآیندهای مبتنی بر فایل‌های اکسل را با یک سیستم Headless مدرن جایگزین می‌کند. این سیستم با تکیه بر Laravel 11 به عنوان بک‌اند، WordPress به عنوان فرانت‌اند و Filament 3.3 به عنوان پنل مدیریت، تجربه‌ای یکپارچه برای اپراتورها و مشتریان فراهم می‌آورد. +**IFNEX** راه‌حل جامعی برای شرکت‌های حمل‌ونقل بین‌المللی است که فرآیندهای مبتنی بر فایل‌های اکسل را با یک سیستم Headless مدرن جایگزین می‌کند. این سیستم با تکیه بر **Laravel 11** به‌عنوان بک‌اند، **WordPress** به‌عنوان فرانت‌اند و **Filament 3.3** به‌عنوان پنل مدیریت، تجربه‌ای یکپارچه برای اپراتورها و مشتریان فراهم می‌آورد. ### ✨ امکانات کلیدی -- **موتور قیمت‌گذاری هوشمند** با ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس (DOC_NORMAL, DOC_ECONOMY, PARCEL) -- **ثبت سفارش آنلاین چندمرحله‌ای** با Wizard و محاسبه لحظه‌ای قیمت -- **تولید خودکار اسناد** (AWB, Invoice, Label) با بارکد استاندارد و پشتیبانی کامل از زبان انگلیسی +- **موتور قیمت‌گذاری هوشمند** با ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس (`DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL`) +- **ثبت سفارش آنلاین چندمرحله‌ای** با Wizard و محاسبهٔ لحظه‌ای قیمت +- **پشتیبانی چندبسته‌ای** (Multi-Package) در یک سفارش با محاسبهٔ خودکار وزن حجمی +- **تولید خودکار اسناد** (AWB، Invoice، Label، فاکتور واردات) با بارکد Code-128 و پشتیبانی کامل از زبان انگلیسی - **پورتال مشتری کامل** با کیف پول، پرداخت آنلاین، تراکنش‌ها، اعلان‌ها و رهگیری مرسوله -- **پنل مدیریت قدرتمند** با Filament 3.3 شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، کاربران و گزارش‌ها -- **سیستم ترکینگ** با قابلیت مهاجرت داده‌های تاریخی و تایم‌لاین کامل +- **فلوی تأیید سفارش** با مسیر `pending_approval → approved → paid → processed` +- **چرخهٔ تعهدنامه** با فلوی کامل End-to-End (دانلود قالب ← آپلود امضاشده ← تأیید یا رد ادمین ← اعلان مشتری) +- **سیستم اعتبار چندارزی** — بدهی به همان ارز ثبت می‌شود، تسویه با نرخ روز +- **مانده حساب** با نمایش موجودی کیف پول منهای بدهی‌های تأییدشده +- **وضعیت مالی مشتری** — صفحهٔ جامع در پنل ادمین (۴ KPI + بدهی‌های ارزی + سفارش‌ها و تراکنش‌ها) +- **ویجت هشدار بدهی‌های ارزی** روی داشبورد به‌همراه badge روی منو +- **چک‌لیست خودکار کارمند** — نمونه‌سازی از قالب پس از تأیید سفارش +- **ایمپورت گروهی وضعیت ترکینگ** با فایل CSV در پنل مدیریت +- **سیستم Audit Log** برای ثبت لاگ تغییرات مدیر +- **پنل مدیریت قدرتمند Filament** شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، کاربران و گزارش‌ها +- **سیستم ترکینگ** با مهاجرت داده‌های تاریخی و تایم‌لاین کامل - **اعلان‌های دیتابیس** برای ادمین و مشتری با badge unread در سایدبار -- **پشتیبانی از ۱۹۲ کشور** با پیش‌شماره تلفن استاندارد ISO 3166-1 -- **اعتبارسنجی فرم‌ها** شامل تشخیص خودکار زبان فارسی/انگلیسی و پیش‌شماره خودکار -- **سیستم تأیید سفارش** با فلوی `pending_approval → approved → paid → processed` -فرم تعهدنامه با فلوی کامل E2E (دانلود قالب → آپلود امضاشده → تأیید/رد ادمین → اعلان مشتری) -فاکتور واردات با طراحی مطابق Sheet ENG Invoice -مانده حساب با نمایش موجودی کیف پول منهای بدهی‌ها -وضعیت مالی مشتری — صفحه جامع در پنل ادمین (۴ KPI + بدهی‌های ارزی + سفارشات/تراکنش‌ها) -سیستم اعتبار چندارزی — بدهی به همان ارز ثبت، تسویه با نرخ روز (EUR/USD/AED/CNY) -ویجت هشدار بدهی‌های ارزی روی داشبورد + badge روی منو -چک‌لیست خودکار کارمند — نمونه‌سازی از قالب بعد از تأیید سفارش -ایمپورت گروهی وضعیت ترکینگ با فایل CSV -سیستم Audit Log برای لاگ تغییرات مدیر -Rate Limiting روی همه APIها (۶ لایه: auth/sms/public/customer/wallet/staff) -بازطراحی داشبورد + لاگین با هویت بصری IFNEX (navy + amber) -بازطراحی PDF — AWB (A4 عرضی) + Invoice + Label (A5 عرضی) با dompdf -اتصال سرویس اس‌ام‌اس Kavenegar برای تأیید موبایل و ارسال پیامک - +- **Rate Limiting** روی همهٔ APIها (۶ لایه: auth / sms / public / customer / wallet / staff) +- **پشتیبانی از ۱۹۲ کشور** با پیش‌شمارهٔ تلفن استاندارد ISO 3166-1 +- **اعتبارسنجی فرم‌ها** با تشخیص خودکار زبان فارسی/انگلیسی و پیش‌شمارهٔ خودکار +- **سرویس پیامک Kavenegar** برای تأیید موبایل و ارسال اعلان وضعیت سفارش --- ## 🏗️ معماری سیستم -این پروژه بر اساس الگوی **Headless** طراحی شده است — فرانت‌اند (WordPress) و بک‌اند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند. این جداسازی به ما امکان می‌دهد تا هر لایه را مستقل مقیاس‌پذیر کنیم، امنیت را بهبود ببخشیم و در آینده فرانت‌اند‌های دیگری (مثل اپلیکیشن موبایل) را اضافه کنیم. +این پروژه بر اساس الگوی **Headless** طراحی شده است — فرانت‌اند (WordPress) و بک‌اند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند. این جداسازی امکان مقیاس‌پذیری مستقل هر لایه، بهبود امنیت و افزودن فرانت‌اندهای آینده (مثل اپلیکیشن موبایل) را می‌دهد. -``` +```text ┌──────────────────────────────────────────────────────┐ │ CLIENT BROWSER │ └────────────────────────┬─────────────────────────────┘ @@ -78,7 +75,7 @@ Rate Limiting روی همه APIها (۶ لایه: auth/sms/public/customer/walle │ │ Filament │ │ API │ │ Services │ │ │ │ Admin Panel │ │ Controllers │ │ (Pricing,│ │ │ │ (/panel) │ │ (/api/v1) │ │ PDF, │ │ -│ └─────────────────┘ └──────┬───────┘ │ Payment)│ │ +│ └─────────────────┘ └──────┬───────┘ │ Payment) │ │ └──────────────────────────────┼──────────┴──────────┘ │ ┌────────────▼────────────┐ @@ -90,25 +87,25 @@ Rate Limiting روی همه APIها (۶ لایه: auth/sms/public/customer/walle ### جریان احراز هویت -``` +```text ┌──────────┐ ┌─────────────────┐ ┌──────────────┐ │ WordPress│ ──POST /bridge/login──> │ Laravel Bridge │ ──> │ Sanctum Token│ │ Plugin │ <──token + user info── │ Controller │ <── │ (30 days) │ └──────────┘ └─────────────────┘ └──────────────┘ │ │ │ ──────── All subsequent API calls with Bearer Token ──────────────>│ -└─────────────────────────────────────────────────────────────────────────┘ + └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## 📁 ساختار پروژه -``` +```text IFNEX-Logistics/ ├── 📄 01_Documents/ # مستندات فنی پروژه -│ ├── IFNEX_File_Map.md # نقشه کامل ۱۰۰+ فایل -│ ├── IFNEX_Roadmap.md # نقشه راه ۴ فازی +│ ├── IFNEX_File_Map.md # نقشهٔ کامل ۱۰۰+ فایل +│ ├── IFNEX_Roadmap.md # نقشهٔ راه فازی │ ├── IFNEX_Phase0_Checklist.md # چک‌لیست تکمیل فازها │ ├── IFNEX_ADR.md # تصمیمات معماری (ADR-001 تا 009) │ └── EXCEL_ANALYSIS.md # تحلیل داده‌های تاریخی @@ -116,123 +113,128 @@ IFNEX-Logistics/ ├── 🌐 03_WordPress/ # فرانت‌اند (WordPress 7.0.3) │ └── wp-content/ │ ├── themes/ifnex/ # قالب سفارشی IFNEX -│ └── plugins/ -│ └── ifnex-bridge/ # پلاگین ارتباط با لاراول -│ ├── includes/ -│ │ ├── api-client.php # مستقیم به API -│ │ ├── user-bridge.php # Bridge Auth + AJAX handlers -│ │ ├── shortcodes.php # ۱۰+ شورت‌کد -│ │ └── tracking-form.php # فرم رهگیری -│ └── assets/ -│ ├── css/ifnex-orders.css # استایل دشبورد -│ └── js/ifnex-order-form.js # فرم چندمرحله‌ای +│ └── plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول +│ ├── includes/ +│ │ ├── api-client.php # ارتباط مستقیم با API +│ │ ├── user-bridge.php # احراز هویت Bridge + AJAX handlers +│ │ ├── shortcodes.php # ۱۰+ شورت‌کد +│ │ └── tracking-form.php # فرم رهگیری +│ └── assets/ +│ ├── css/ifnex-orders.css # استایل داشبورد +│ └── js/ifnex-order-form.js # فرم چندمرحله‌ای │ ├── ⚙️ 04_Laravel/ # بک‌اند (Laravel 11) │ ├── app/ -│ │ ├── Enums/ # ShipmentStatus, Direction, Type +│ │ ├── Enums/ # ShipmentStatus، Direction، Type │ │ ├── Filament/ -│ │ │ ├── Resources/ # 10+ Resource (Shipment, Country, ...) -│ │ │ ├── Pages/ # Settings, ImportRates, PriceTest, Reports -│ │ │ └── Widgets/ # Dashboard Widgets +│ │ │ ├── Resources/ # ۱۷ Resource (Shipment، Country و…) +│ │ │ ├── Pages/ # Settings، ImportRates، PriceTest، Reports +│ │ │ └── Widgets/ # داشبورد │ │ ├── Http/ -│ │ │ ├── Controllers/Api/ # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment +│ │ │ ├── Controllers/Api/ # Track، Pricing، Auth، Bridge، Customer، Wallet، Payment │ │ │ └── Middleware/ # ApiKeyMiddleware -│ │ ├── Models/ # 13 مدل Eloquent -│ │ ├── Notifications/ # Database notifications -│ │ ├── Services/ # PriceCalculator, Pdf, Tracking, OrderPayment -│ │ └── Imports/ # Excel imports (OldShipments, ShippingRates) +│ │ ├── Models/ # ۲۶ مدل Eloquent +│ │ ├── Notifications/ # اعلان‌های دیتابیسی +│ │ ├── Services/ # PriceCalculator، Pdf، Tracking، OrderPayment +│ │ └── Imports/ # ایمپورت اکسل (OldShipments، ShippingRates) │ ├── database/ -│ │ ├── migrations/ # 23 migrations -│ │ └── seeders/ # Countries, SystemSettings, DatabaseSeeder +│ │ ├── migrations/ # ۵۲ migration +│ │ └── seeders/ # Countries، SystemSettings، DatabaseSeeder │ ├── resources/views/ -│ │ ├── pdfs/ # awb, invoice, label +│ │ ├── pdfs/ # awb، invoice، label، import-invoice │ │ └── filament/ # Blade views │ └── routes/ -│ ├── api.php # 30+ REST API endpoints -│ └── web.php # Web routes + Download Template +│ ├── api.php # ۴۰+ endpoint +│ └── web.php # روت‌های وب + دانلود Template │ -├── 📋 README.md # این فایل +├── 📋 README.md # همین فایل +├── 📋 AGENT.md # راهنمای ایجنت +├── 📋 CLIENT_DELIVERY.md # چک‌لیست وضعیت تحویل مشتری (منبع اصلی) ├── 📋 DEPLOYMENT.md # راهنمای استقرار Production -└── 📋 04_Laravel/README.md # راهنمای بک‌اند +└── 📋 DEPLOYMENT_HANDOFF.md # تحویل استقرار به تیم IT کارفرما ``` --- -## ✨ ویژگی‌های کلیدی بر اساس فازها +## ✨ ویژگی‌ها بر اساس فازها + +### فاز ۰ — بنیان سیستم ✅ (۱۰۰٪) -### فاز ۰ — بنیان سیستم ✅ (تکمیل شده - 100%) - اسکیمای دیتابیس مدرن با ۴ زون مجزا (Export/Import × Parcel/Doc) - مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل به دیتابیس - پنل مدیریت Filament با UX تخصصی اپراتور -- API ترکینگ با امنیت API Key + Rate Limiting +- API ترکینگ با امنیت کلید API و Rate Limiting - پلاگین WordPress Bridge برای ارتباط با فرانت‌اند -### فاز ۱ — پورتال مشتری ✅ (تکمیل شده - 100%) +### فاز ۱ — پورتال مشتری ✅ (۱۰۰٪) + - احراز هویت Laravel Sanctum + Bridge Auth (بدون نیاز به رمز عبور) - فرم ثبت سفارش چندمرحله‌ای با Wizard (مسیر، اطلاعات تماس، تخفیف، تأیید) -- داشبورد جامع مشتری شامل: داشبورد، سفارشات، ثبت سفارش، کیف پول، تراکنش‌ها، رهگیری، اعلان‌ها، پروفایل -- سیستم ترکینگ با تایم‌لاین و تاریخچه کامل +- داشبورد جامع مشتری: داشبورد، سفارش‌ها، ثبت سفارش، کیف پول، تراکنش‌ها، رهگیری، اعلان‌ها، پروفایل +- سیستم ترکینگ با تایم‌لاین و تاریخچهٔ کامل + +### فاز ۲ — مالی و کیف پول ✅ (۱۰۰٪) -### فاز ۲ — مالی و کیف پول ✅ (تکمیل شده - 100%) - سیستم کیف پول کامل با تراکنش‌ها و تاریخچه - درگاه پرداخت Zarinpal + Mock Gateway برای تست لوکال -- مدیریت ارزهای چندگانه (IRR, AED, USD, EUR, CNY) +- مدیریت ارزهای چندگانه (IRR، AED، USD، EUR، CNY) - کدهای تخفیف با اعتبارسنجی و محدودیت مصرف -- تولید PDF حرفه‌ای (AWB, Invoice, Label) با بارکد استاندارد +- تولید PDF حرفه‌ای (AWB، Invoice، Label) با بارکد استاندارد - پشتیبانی از چند بسته در یک سفارش (Multi-Package) -- تاریخچه تغییرات وضعیت (ShipmentStatusHistory) +- تاریخچهٔ تغییرات وضعیت (ShipmentStatusHistory) + +### فاز ۳ — بهبود و یکپارچه‌سازی ✅ (۱۰۰٪) -### فاز ۳ — بهبود و یکپارچه‌سازی ✅ (تکمیل شده - 100%) - ایمپورت/اکسپورت نرخ‌ها با دانلود Template اکسل - سیستم اعلان‌های دیتابیس (ادمین + مشتری) با badge unread در سایدبار - هشدار هوشمند زبان فارسی/انگلیسی در فرم سفارش (نام، شهر، آدرس) -- پیش‌شماره تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور) -- اعتبارسنجی تلفن (فقط اعداد، +، فاصله) -- استایل مدرن تراکنش‌ها و دشبورد مشتری -- صفحه شارژ کیف پول با مبالغ آماده -- بازطراحی PDFها (AWB, Invoice, Label) با بارکد مطابق نمونه کارفرما -- اصلاح متدهای Enum (isPaid, canBeCancelledByCustomer) -- میدلور API برای بازگرداندن JSON 401 به جای redirect +- پیش‌شمارهٔ تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور) +- اعتبارسنجی تلفن (فقط اعداد، `+` و فاصله) +- استایل مدرن تراکنش‌ها و داشبورد مشتری +- صفحهٔ شارژ کیف پول با مبالغ آماده +- بازطراحی PDFها (AWB، Invoice، Label) با بارکد مطابق نمونهٔ کارفرما +- اصلاح متدهای Enum (`isPaid`، `canBeCancelledByCustomer`) +- میدلور API برای بازگرداندن JSON 401 به‌جای redirect -### فاز ۳.۵ — اصلاحات اساسی ✅ (تکمیل شده - 90%) -- **Multi-Package** در فرم سفارش مشتری (چند بسته در یک سفارش) -- **فرم Invoice** برای محموله‌های PARCEL (اقلام گمرکی با HS Code) -- **بازطراحی PDFها** (AWB, Invoice, Label) با بارکد مطابق نمونه کارفرما -- **تست ترکینگ** کامل با timeline زیبا و چندمرحله‌ای -- محاسبه خودکار وزن حجمی از ابعاد (فرمول: L×W×H/5000) -- ساختار ۵ مرحله‌ای فرم سفارش (مسیر → تماس → اقلام → تخفیف → تأیید) -- اصلاحات فنی (Enum casts, migration, model) -- پشتیبانی چندزبانه (i18n) — به زمان دیپلوی منتقل شد +### فاز ۳.۵ — اصلاحات اساسی ✅ (۹۰٪) -### فاز ۳.۶ — اصلاحات جلسه کارفرما ✅ (تکمیل شده - ۹۵٪) -هدف: پیاده‌سازی تغییرات درخواستی کارفرما پس از جلسه ارائه +- Multi-Package در فرم سفارش مشتری (چند بسته در یک سفارش) +- فرم Invoice برای محموله‌های PARCEL (اقلام گمرکی با HS Code) +- بازطراحی PDFها (AWB، Invoice، Label) با بارکد مطابق نمونهٔ کارفرما +- تست کامل ترکینگ با تایم‌لاین چندمرحله‌ای +- محاسبهٔ خودکار وزن حجمی از ابعاد (فرمول: `L × W × H / 5000`) +- ساختار ۵ مرحله‌ای فرم سفارش (مسیر ← تماس ← اقلام ← تخفیف ← تأیید) +- اصلاحات فنی (Enum casts، migration، model) +- پشتیبانی چندزبانه (i18n) — منتقل شد به زمان دیپلوی -✅ فلوی تأیید سفارش: pending_approval → approved → (پرداخت) → processed — E2E تست شد -✅ تعهدنامه‌ها: فلوی کامل (دانلود قالب → آپلود امضاشده → تأیید/رد ادمین → اعلان مشتری) -✅ دانلود اسناد سفارش (AWB, Invoice, Label, فاکتور واردات) در پورتال مشتری -✅ صفحه «وضعیت مالی مشتری» در پنل ادمین (۴ KPI + بدهی ارزی + سفارشات/تراکنش‌ها) -✅ سیستم اعتبار چندارزی کامل (درخواست ۹) — CustomerCreditService + نمایش در پورتال مشتری -✅ ویجت هشدار بدهی‌های ارزی روی داشبورد + badge قرمز روی منو -✅ چک‌لیست خودکار بعد از تأیید سفارش (درخواست ۵) — instantiateChecklist() -✅ Rate Limiting روی همه APIها (۶ لایه throttle) -✅ ایمپورت گروهی وضعیت ترکینگ با CSV در پنل (BulkTrackingImport) -✅ Audit Log برای مدل‌های اصلی + ShipmentStatusHistory با from/to_status -✅ اتصال SMS کاوه‌نگار: تأیید/رد سفارش، پرداخت موفق، بروزرسانی ترکینگ + تنظیمات پنل -✅ فاکتور واردات (Import Invoice) با فیلدهای جدید shipments + قالب PDF -✅ مانده حساب (موجودی منهای بدهی‌های تأییدشده) در پروفایل مشتری -✅ بازطراحی داشبورد + لاگین Filament (navy + amber brand identity) -✅ بازطراحی AWB + Invoice + Label PDF (dompdf, table-based, DHL-style) -✅ استایل‌دهی صفحه پروفایل مشتری در وردپرس -✅ پاک‌سازی کد — حذف فایل‌های تستی، تأیید تمیزی opcache_reset/dd/dump -⏳ باقی‌مانده: i18n (زمان دیپلوی) + سند پیشنهادی سیستم مالی (آینده) +### فاز ۳.۶ — اصلاحات جلسهٔ کارفرما ✅ (۹۵٪) +- [x] فلوی تأیید سفارش `pending_approval → approved → پرداخت → processed` — تست End-to-End +- [x] تعهدنامه‌ها با فلوی کامل (دانلود قالب ← آپلود امضاشده ← تأیید/رد ادمین ← اعلان مشتری) +- [x] دانلود اسناد سفارش (AWB، Invoice، Label، فاکتور واردات) در پورتال مشتری +- [x] صفحهٔ «وضعیت مالی مشتری» در پنل ادمین (۴ KPI + بدهی ارزی + سفارش‌ها و تراکنش‌ها) +- [x] سیستم اعتبار چندارزی کامل (درخواست ۹) — `CustomerCreditService` + نمایش در پورتال مشتری +- [x] ویجت هشدار بدهی‌های ارزی روی داشبورد + badge قرمز روی منو +- [x] چک‌لیست خودکار پس از تأیید سفارش (درخواست ۵) — `instantiateChecklist()` +- [x] Rate Limiting روی همهٔ APIها (۶ لایه throttle) +- [x] ایمپورت گروهی وضعیت ترکینگ با CSV در پنل (`BulkTrackingImport`) +- [x] Audit Log برای مدل‌های اصلی + `ShipmentStatusHistory` با `from_status` / `to_status` +- [x] اتصال SMS کاوه‌نگار: تأیید/رد سفارش، پرداخت موفق، به‌روزرسانی ترکینگ + تنظیمات پنل +- [x] فاکتور واردات (Import Invoice) با فیلدهای جدید shipments + قالب PDF +- [x] مانده حساب (موجودی منهای بدهی‌های تأییدشده) در پروفایل مشتری +- [x] بازطراحی داشبورد و Login فیلمنت (هویت بصری navy + amber) +- [x] بازطراحی AWB، Invoice و Label (dompdf، چیدمان جدولی، سبک DHL) +- [x] استایل‌دهی صفحهٔ پروفایل مشتری در وردپرس +- [x] پاک‌سازی کد — حذف فایل‌های تستی، تأیید تمیزی `opcache_reset` / `dd` / `dump` ### فاز ۴ (آینده) — سیستم نمایندگی 📋 + - مدل نمایندگی کامل با کمیسیون و پنل جداگانه - طرح مطالعاتی آماده — منتظر تأیید کارفرما ### فاز ۵ (آینده) — تجاری‌سازی 📋 -- مدل پولی چندلایه‌ای: Starter / Business / Enterprise + +- مدل پولی چندلایه: Starter / Business / Enterprise - فرم‌ساز Drag & Drop - White-label branding - API Gateway برای توسعه‌دهندگان @@ -242,7 +244,8 @@ IFNEX-Logistics/ ## ⚡ شروع سریع ### پیش‌نیازها -- PHP 8.2+ با extensions: pdo_mysql, mbstring, xml, gd, zip + +- PHP 8.2+ با اکستنشن‌های `pdo_mysql`، `mbstring`، `xml`، `gd`، `zip` - Composer 2.x - MySQL 8+ - WordPress 7.0+ @@ -268,8 +271,8 @@ mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8 # DB_DATABASE=ifnex_db # DB_USERNAME=root # DB_PASSWORD=your_password -# IFNEX_BRIDGE_API_KEY=your-secret-bridge-key # مهم برای وردپرس -# ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing # برای Mock Mode +# IFNEX_BRIDGE_API_KEY=your-secret-bridge-key # مهم برای وردپرس +# ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing # برای Mock Mode # ZARINPAL_SANDBOX=true # CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1 @@ -284,46 +287,51 @@ php artisan serve ### نصب فرانت‌اند (WordPress) -```bash -# ۱. کپی پوشه 03_WordPress به htdocs (XAMPP) یا public_html (سرور) -# ۲. ساخت دیتابیس وردپرس و اجرای نصب -# ۳. فعال‌سازی قالب IFNEX و پلاگین IFNEX Bridge -# ۴. تنظیمات پلاگین (admin → منوی IFNEX): -# - API URL: http://localhost:8000/api/v1 -# - API Key (عمومی): همان مقدار IFNEX_API_KEY در .env لاراول -# - Bridge API Key: همان مقدار IFNEX_BRIDGE_API_KEY در .env لاراول -# ۵. ساخت صفحات با شورت‌کدها: -# - /my-account/ → [ifnex_customer_dashboard] -# - /my-orders/ → [ifnex_orders_list] -# - /new-order/ → [ifnex_order_form] -# - /wallet/ → [ifnex_wallet_charge] -# - /tracking/ → [ifnex_tracking_form] -``` +1. پوشهٔ `03_WordPress` را در `htdocs` (XAMPP) یا `public_html` (سرور) کپی کنید. +2. دیتابیس وردپرس را بسازید و نصب را اجرا کنید. +3. قالب IFNEX و پلاگین IFNEX Bridge را فعال کنید. +4. تنظیمات پلاگین را کامل کنید (پنل وردپرس ← منوی IFNEX): -> 📖 برای راهنمای کامل استقرار روی سرور، [DEPLOYMENT.md](DEPLOYMENT.md) را ببینید. + | تنظیم | مقدار | + |--------|--------| + | API URL | `http://localhost:8000/api/v1` | + | API Key (عمومی) | همان مقدار `IFNEX_API_KEY` در `.env` لاراول | + | Bridge API Key | همان مقدار `IFNEX_BRIDGE_API_KEY` در `.env` لاراول | + +5. صفحات را با شورت‌کدها بسازید: + + | صفحه | شورت‌کد | + |------|---------| + | `/my-account/` | `[ifnex_customer_dashboard]` | + | `/my-orders/` | `[ifnex_orders_list]` | + | `/new-order/` | `[ifnex_order_form]` | + | `/wallet/` | `[ifnex_wallet_charge]` | + | `/tracking/` | `[ifnex_tracking_form]` | + +> 📖 برای راهنمای کامل استقرار روی سرور، [DEPLOYMENT.md](DEPLOYMENT.md) و [DEPLOYMENT_HANDOFF.md](DEPLOYMENT_HANDOFF.md) را ببینید. --- -## 🛠️ Stack فنی +## 🛠️ استک فنی -### Backend (Laravel) +### بک‌اند (Laravel) | تکنولوژی | نسخه | کاربرد | -|-----------|------|--------| +|-----------|-------|--------| | Laravel | 11.x | فریمورک اصلی | | PHP | 8.2+ | زبان برنامه‌نویسی | | Filament | 3.3.x | پنل مدیریت ادمین | | MySQL | 8+ | دیتابیس | | Dompdf | Latest | تولید PDF | -| Laravel Excel | Latest | Import/Export | -| Sanctum | Latest | API Authentication | +| Laravel Excel | Latest | Import / Export | +| Sanctum | Latest | احراز هویت API | | Morilog Jalali | 3.x | تاریخ شمسی | | picqer/php-barcode | Latest | تولید بارکد | -### Frontend (WordPress) +### فرانت‌اند (WordPress) | تکنولوژی | نسخه | کاربرد | -|-----------|------|--------| +|-----------|-------|--------| | WordPress | 7.0.3 | CMS | | IFNEX Theme | Custom | قالب سفارشی | | IFNEX Bridge | 1.7.0 | پلاگین ارتباطی | @@ -359,18 +367,20 @@ php artisan serve ## 📚 مستندات -برای مطالعه دقیق منطق‌های سیستم: +برای مطالعهٔ دقیق منطق‌های سیستم: | فایل | محتوا | اولویت | -|------|-------|--------| -| [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) | نقشه ۱۰۰+ فایل پروژه | ⭐⭐⭐ | -| [IFNEX_I18N_Strategy.md](01_Documents/IFNEX_I18N_Strategy.md) | استراتژی چندزبانه (Polylang) | ⭐⭐ | -| [IFNEX_Commercial_Model.md](01_Documents/IFNEX_Commercial_Model.md) | مدل تجاری و پلن‌های فروش | ⭐⭐ | +|------|-------|---------| +| [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) | **چک‌لیست وضعیت تحویل مشتری (منبع اصلی)** | ⭐⭐⭐ | +| [DEPLOYMENT_HANDOFF.md](DEPLOYMENT_HANDOFF.md) | راهنمای استقرار برای تیم IT کارفرما | ⭐⭐⭐ | +| [AGENT.md](AGENT.md) | راهنمای ایجنت، مفاهیم کلیدی و خط قرمزها | ⭐⭐⭐ | +| [01_Documents/IFNEX_Phase0_Checklist.md](01_Documents/IFNEX_Phase0_Checklist.md) | چک‌لیست کامل فازها | ⭐⭐ | +| [01_Documents/IFNEX_Roadmap.md](01_Documents/IFNEX_Roadmap.md) | نقشهٔ راه آینده (فاز ۴ و ۵) | ⭐⭐ | +| [01_Documents/IFNEX_File_Map.md](01_Documents/IFNEX_File_Map.md) | نقشهٔ ۱۰۰+ فایل پروژه | ⭐⭐ | | [DEPLOYMENT.md](DEPLOYMENT.md) | راهنمای استقرار Production | ⭐⭐ | | [04_Laravel/README.md](04_Laravel/README.md) | راهنمای بک‌اند | ⭐⭐ | -| [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) | **چک‌لیست وضعیت تحویل مشتری (منبع اصلی)** | ⭐⭐⭐ | +| [01_Documents/IFNEX_I18N_Strategy.md](01_Documents/IFNEX_I18N_Strategy.md) | استراتژی چندزبانه (Polylang) | ⭐ | +| [01_Documents/IFNEX_Commercial_Model.md](01_Documents/IFNEX_Commercial_Model.md) | مدل تجاری و پلن‌های فروش | ⭐ | --- @@ -378,24 +388,25 @@ php artisan serve > 📌 **فهرست دقیق و به‌روزِ وضعیت تحویل در [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) نگهداری می‌شود** — این بخش فقط نمای کلی است. -### فاز ۳.۶ — باقیمانده (آینده) -⏳ سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) — موکول به آینده -⏳ چندزبانه (i18n) — موکول به زمان دیپلوی -✅ همه موارد اصلی فاز ۳.۶ تکمیل شد (2026-10-04) — فلوی E2E، اعتبار چندارزی، Rate Limiting، چک‌لیست خودکار، بازطراحی UI/PDF، پاک‌سازی. +### باقی‌ماندهٔ فاز ۳.۶ +- ⏳ چندزبانه (i18n) با Polylang — موکول به زمان دیپلوی +- ⏳ سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) — موکول به آینده +- ⏳ تست نهایی UAT کارفرما +- ⏳ دیپلوی روی سرور Production - -### فاز ۳.۵ — باقیمانده (زمان دیپلوی) -- پشتیبانی کامل چندزبانه (i18n) با Polylang +> ✅ همهٔ موارد اصلی فاز ۳.۶ در ۲۰۲۶-۱۰-۰۴ تکمیل شد: فلوی End-to-End، اعتبار چندارزی، Rate Limiting، چک‌لیست خودکار، بازطراحی UI و PDF، و پاک‌سازی کد. ### فاز ۴ (آینده) + - سیستم نمایندگی کامل با کمیسیون و پنل جداگانه ### فاز ۵ (آینده — تجاری‌سازی) -- مدل پولی چندلایه‌ای: Starter / Business / Enterprise -- اتصال به APIهای ترکینگ زنده (TrackingMore/17track) + +- مدل پولی چندلایه: Starter / Business / Enterprise +- اتصال به APIهای ترکینگ زنده (TrackingMore / 17track) - پلاگین SMS برای اطلاع‌رسانی خودکار -- مستندات API (OpenAPI/Swagger) +- مستندات API (OpenAPI / Swagger) - راهنمای اپراتور (Operator Manual) - تست‌های واحد و Integration - اپلیکیشن موبایل (احتمالی) @@ -407,10 +418,12 @@ php artisan serve ## 📞 تماس -- **توسعه‌دهنده:** Kazem Alghasi -- **شرکت:** VernaSoft Group -- **ایمیل:** kazem@vernasoft.group -- **مخزن:** [git.vernahost.ir/gitmodir110/ifnex](https://git.vernahost.ir/gitmodir110/ifnex) +| مورد | مقدار | +|------|-------| +| توسعه‌دهنده | Kazem Alghasi | +| شرکت | VernaSoft Group | +| ایمیل | kazem@vernasoft.group | +| مخزن | [git.vernahost.ir/gitmodir110/ifnex](https://www.git.vernahost.ir/gitmodir110/ifnex) | --- @@ -420,6 +433,6 @@ php artisan serve © 2026 VernaSoft Group. تمام حقوق محفوظ است. -این پروژه طبق سفارش IFNEX و مالکیت آن برای گروه ورناسافت است و کپی یا استفاده غیرمجاز ممنوع می‌باشد. +این پروژه طبق سفارش IFNEX و مالکیت آن برای گروه ورناسافت است و کپی یا استفادهٔ غیرمجاز ممنوع می‌باشد.