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