ifnex/CLIENT_DELIVERY.md

IFNEX — Client Delivery Checklist

وضعیت تحویل نسخه فعلی 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

Requirement: در بخش Hero صفحه اصلی WordPress، گزینه «ردیابی مرسوله» باید کاربر را به صفحه اختصاصی Tracking هدایت کند.

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 در صورت نیاز

---

2.2 New Order — Multi-Step Form

Step 1 → Step 2

Requirement: پس از تکمیل مرحله اول فرم ثبت سفارش، مرحله دوم بدون خطا Load شود.

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
• حفظ اطلاعات مراحل قبلی

---

3. Customer Dashboard / Financial Status

3.1 Customer Balance

Requirement: در Dashboard مشتری، علاوه بر Wallet Balance و Orders، مانده حساب مشتری نیز نمایش داده شود.

فرمول مورد انتظار:

Available Balance / 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

Requirement: مشتری بلافاصله پس از ثبت سفارش نباید وارد درگاه شود.

Status: 🟡 Implemented — Needs End-to-End Verification

---

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:

• 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 تست و تأیید شد.

---

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 عملیاتی وجود داشته باشد.

هر Checklist Item باید حداقل شامل موارد زیر باشد:

Item Status Required / Optional Completed By Completed At Note Attachment (when needed) Manager Requirements:

مشاهده تمام مراحل مشاهده کارمند انجام‌دهنده مشاهده تاریخ و ساعت مشاهده موارد ناقص امکان گزارش‌گیری

Status: ✅ Implemented — Auto-Instantiated on Approval

🔧 به‌روزرسانی 2026-10-04: چک‌لیست به‌صورت خودکار بعد از تأیید سفارش (ShipmentReviewService::approve)از قالب‌های فعال (ShipmentChecklistTemplate) نمونه‌سازی می‌شود.مدیریت کامل در ChecklistsRelationManager روی ShipmentResource + ShipmentChecklistResource.اکشن‌های تکمیل/تکمیل گروهی + فیلد completed_by و completed_at پیاده‌سازی شد.

---

6. Shipment History / Timeline

Requirement: مدیر بتواند تاریخچه کامل هر Shipment را از شروع تا پایان مشاهده کند.

هر تغییر باید تا حد امکان شامل موارد زیر باشد:

• Previous Status
• New Status
• User / Employee
• Date
• Time
• Note

Status: 🟡 Implemented — Needs Final Verification

---

7. PDF Documents

Required Documents

• AWB
• Invoice
• Label
• Import Invoice
• Commitment Documents where applicable

Requirement: طراحی PDFها باید تا حد امکان مطابق نمونه‌های Excel / Client Documents باشد.

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 — نیاز به تست چاپ فیزیکی

---

8. Customer Financial Information — Staff / Manager

Requirement: کارمند یا مدیر بتواند با انتخاب یا جستجوی مشتری، اطلاعات مالی کامل او را مشاهده کند.

Required Information

• 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.

---

9. Customer Credit

Requirement: فقط مدیر کل بتواند برای مشتری شناخته‌شده Credit ایجاد یا افزایش دهد.

Important Rule

اگر مشتری:

50 EUR

بدهکار است، بدهی باید به صورت:

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ها در پنل مدیریت.

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

Requirement: مدیر بتواند تقریباً همه اطلاعات عملیاتی لازم را ویرایش کند.

Important Rule: تغییرات مدیریتی باید قابل Audit باشند.

Audit Information

• User
• Action
• Model
• Record
• Old Value
• New Value
• Date
• Time
• IP where applicable

Status: 🟡 Implemented — Needs Security / Authorization Verification

---

12. SMS Integration

Provider: Kavenegar

Required Use Cases

• 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

---

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 ✅ (بدهی به همان ارز ثبت، نه معادل ریالی)

✅ انجام شد (2026-10-03): تغییر نرخ ارز فقط از منوی «نرخ ارز» (تاریخچه + گردش تأیید + آپدیت از API) — فیلدهای مستقیم نرخ در «تنظیمات سیستم» حذف و به نمایش فقط‌خواندنی تبدیل شدند.

Application

• Legacy Order Flow review
• Exception handling
• Production logging
• Cache / OPcache configuration
• Asset versioning

---

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

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

Manager / Super Admin

• Customer Financial Review
• Grant Credit
• Modify Credit
• Review Audit
• View Shipment Timeline
• Edit Operational Data
• Review Staff Activity

---

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 محصول شود.