# IFNEX — چک‌لیست تحویل به مشتری

> **وضعیت:** آماده برای دیپلوی (۹۵٪ تکمیل)
> **فاز جاری:** فاز ۳.۶ — اصلاحات جلسهٔ کارفرما
> **تاریخ آخرین به‌روزرسانی:** ۲۰۲۶-۱۰-۰۴
> **مخزن:** [git.vernahost.ir/gitmodir110/ifnex](https://www.git.vernahost.ir/gitmodir110/ifnex)

> ⚠️ این فایل فقط برای مدیریت تعهدات، تست و تحویل نسخهٔ فعلی مشتری است و جایگزین `AGENT.md` یا `IFNEX_Roadmap.md` نیست.

---

## راهنمای وضعیت‌ها

| نشان | معنی |
|------|------|
| ✅ | تکمیل‌شده |
| 🟡 | پیاده‌سازی‌شده — نیازمند تأیید نهایی |
| ⏳ | در انتظار |
| 🔴 | مسدود |
| ❌ | پیاده‌سازی‌نشده |

---

# ۱. فرانت‌اند و صفحهٔ اصلی

## ۱.۱ هدایت دکمهٔ ردیابی مرسوله

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

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |
| فایل‌ها | `03_WordPress/wp-content/themes/ifnex/`<br>`03_WordPress/wp-content/plugins/ifnex-bridge/` |

**تست پذیرش:**

- [ ] کلیک روی دکمهٔ CTA
- [ ] ریدایرکت صحیح انجام می‌شود
- [ ] URL مقصد صحیح است
- [ ] صفحهٔ Tracking درست نمایش داده می‌شود
- [ ] رفتار در حالت Login و Guest بررسی شد

---

## ۱.۲ فرم ثبت سفارش چندمرحله‌ای

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

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |
| باگ تاریخی | بسته‌نبودن یک `div` در فایل `shortcodes.php` |
| فایل‌ها | `includes/shortcodes.php`<br>`assets/js/ifnex-order-form.js` |

**تست پذیرش:**

- [ ] حرکت رو به جلو بین مراحل
- [ ] حرکت رو به عقب بین مراحل
- [ ] اعتبارسنجی فرم در هر مرحله
- [ ] حفظ اطلاعات مراحل قبلی
- [ ] Console مرورگر بدون Error
- [ ] رفتار Export و Import بررسی شد

---

# ۲. داشبورد مشتری و وضعیت مالی

## ۲.۱ مانده حساب مشتری

**الزام مشتری:** در داشبورد مشتری، علاوه بر موجودی کیف پول و سفارش‌ها، مانده حساب نیز نمایش داده شود.

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

```text
Account Balance = Wallet Balance − Outstanding Approved Obligations
```

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |

**تست پذیرش:**

- [ ] کیف پول مثبت
- [ ] مشتری بدون بدهی
- [ ] مشتری دارای بدهی
- [ ] مشتری با چند سفارش تأییدشده ولی پرداخت‌نشده
- [ ] نمایش صحیح ارز
- [ ] بدهی چندارزی به مبلغ ریالی اشتباه تبدیل نمی‌شود

---

# ۳. تأیید سفارش پیش از پرداخت

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

## ۳.۱ فلوی عمومی

```text
Create Order
  → Pending Approval
  → Staff Review
  → Approved
  → Documents / Commitment Verification
  → Payment Enabled
  → Wallet OR Online Payment
  → Paid
  → Processed
```

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید End-to-End |

## ۳.۲ سفارش 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
```

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |

---

# ۴. چک‌لیست کارمند

**الزام مشتری:** برای هر سفارش یک چک‌لیست عملیاتی وجود داشته باشد.

**فیلدهای اجباری هر آیتم:**

| فیلد |
|------|
| عنوان آیتم |
| وضعیت |
| Required / Optional |
| کارمند تکمیل‌کننده |
| تاریخ و ساعت تکمیل |
| یادداشت |
| پیوست (در صورت نیاز) |

**الزامات مدیر:**

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

| مورد | مقدار |
|------|-------|
| وضعیت | ✅ تکمیل — نمونه‌سازی خودکار پس از تأیید |

**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):**

- چک‌لیست پس از تأیید سفارش (در `ShipmentReviewService::approve`) از قالب‌های فعال (`ShipmentChecklistTemplate`) نمونه‌سازی می‌شود.
- مدیریت کامل در `ChecklistsRelationManager` روی `ShipmentResource` و `ShipmentChecklistResource` انجام می‌شود.
- اکشن‌های تکمیل تکی و گروهی به‌همراه فیلدهای `completed_by` و `completed_at` پیاده‌سازی شدند.

---

# ۵. تاریخچه و تایم‌لاین مرسوله

**الزام مشتری:** مدیر بتواند تاریخچهٔ کامل هر مرسوله را از ابتدا تا انتها مشاهده کند.

هر تغییر وضعیت باید شامل موارد زیر باشد:

- وضعیت قبلی
- وضعیت جدید
- کاربر / کارمند
- تاریخ
- ساعت
- یادداشت

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |

---

# ۶. اسناد PDF

**الزام مشتری:** اسناد AWB، Invoice، Label، فاکتور واردات و تعهدنامه‌ها تولید شوند و طراحی آن‌ها تا حد امکان مطابق نمونه‌های اکسل و اسناد کارفرما باشد.

> **توجه:** تطبیق ۱۰۰٪ پیکسلی به دلیل تفاوت موتور PDF با اکسل ممکن نیست. هدف، نزدیک‌ترین تطبیق عملی و قابل چاپ است.

## ۶.۱ بازطراحی انجام‌شده (۲۰۲۶-۱۰-۰۴)

| سند | طراحی |
|------|-------|
| AWB | A4 افقی، پالت navy + amber، چیدمان جدولی، بارکد در هدر، لوگوی IFNEX، گرید ۴×۱ |
| Invoice | A4 عمودی، طراحی هم‌سبک AWB، فیلدهای خالی با `@if` مخفی، جدول با راه‌راه Zebra |
| Import Invoice | A4 عمودی، بر اساس شیت ENG Invoice |
| Label | A5 افقی، بدون برند (white-label)، تک‌رنگ، بارکد بزرگ، جدول وزن و ابعاد |

همهٔ اسناد با **dompdf** و چیدمان **جدولی** (نه flexbox) تولید می‌شوند تا سازگاری کامل و بدون overflow تضمین شود.

## ۶.۲ وضعیت تأیید PDF

| مورد | وضعیت |
|------|--------|
| AWB | ✅ بازطراحی شد |
| Export Invoice | ✅ بازطراحی شد |
| Import Invoice | ✅ بازطراحی شد — نیازمند تأیید نهایی مشتری |
| Label | ✅ بازطراحی شد |
| بارکد | ✅ Code-128 قابل اسکن |
| چیدمان | ✅ جدولی، بدون overflow |
| تایپوگرافی | ✅ DejaVu Sans / Vazirmatn |
| اندازهٔ صفحه | ✅ A4 افقی (AWB) / A4 عمودی (Invoice) / A5 افقی (Label) |
| خروجی چاپ | ⏳ نیازمند تست چاپ فیزیکی |

| وضعیت کلی بخش | مقدار |
|----------------|-------|
| نتیجه | 🟡 پیاده‌سازی‌شده — در انتظار تأیید نهایی مشتری |

---

# ۷. اطلاعات مالی مشتری (کارمند / مدیر)

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

**اطلاعات مورد نیاز:**

- موجودی فعلی
- مطالبات / بدهی‌ها
- ارز
- تراکنش‌های اخیر
- سفارش‌های اخیر
- شمارهٔ مرجع سفارش
- مبلغ
- وضعیت پرداخت
- تاریخ‌ها
- یادداشت‌ها

| مورد | مقدار |
|------|-------|
| وضعیت | ✅ تکمیل — صفحهٔ نمای کلی مالی مشتری ساخته شد |

**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):**

- صفحهٔ «وضعیت مالی مشتری» در `App\Filament\Pages\CustomerFinancialOverview` ساخته شد.
- مدیر یا کارمند با جستجوی مشتری موارد زیر را می‌بیند:
  - ۴ کارت KPI: موجودی کیف پول، بدهی فعلی، کل پرداختی، مانده حساب
  - جدول بدهی‌های چندارزی به تفکیک ارز (EUR / USD / AED / CNY)
  - ۵ سفارش اخیر و ۵ تراکنش اخیر
  - دکمه‌های اقدام: اعتبار جدید، سفارش‌ها، وضعیت مالی
- طراحی با گرید ۱۲ ستونی و CSS اختصاصی IFNEX انجام شده است.

---

# ۸. اعتبار مشتری (چندارزی)

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

## ۸.۱ قاعدهٔ اصلی

اگر مشتری مثلاً **۵۰ EUR** بدهکار باشد، بدهی باید به همان ارز ثبت شود و **نباید** به مبلغ ریالی روز تبدیل و جایگزین شود.

## ۸.۲ اطلاعات لازم هنگام تسویهٔ ریالی

| فیلد |
|------|
| مبلغ اصلی |
| ارز اصلی |
| ارز تسویه |
| نرخ تبدیل |
| تاریخ نرخ |
| مبلغ تسویه |
| دلیل / مرجع |

| مورد | مقدار |
|------|-------|
| وضعیت | ✅ تکمیل — سیستم اعتبار چندارزی کامل شد |

**نکات پیاده‌سازی (۲۰۲۶-۱۰-۰۴):**

- `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` مجاز به اعطای اعتبار است

---

# ۹. ایمپورت گروهی وضعیت ترکینگ

**الزام مشتری:** امکان Import گروهی آخرین وضعیت Trackingها در پنل مدیریت.

| مورد | مقدار |
|------|-------|
| ورودی | فایل CSV یا فرمت Import تأییدشده |
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |

**خروجی مورد انتظار:**

- یافتن مرسوله
- اعتبارسنجی شمارهٔ ترکینگ
- به‌روزرسانی وضعیت
- ثبت تاریخچه
- ثبت نتیجهٔ Import
- گزارش ردیف‌های ناموفق

---

# ۱۰. ویرایش مدیریتی و Audit Log

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

> **قاعدهٔ مهم:** تغییرات مدیریتی باید قابل Audit باشند.

**اطلاعات Audit:**

- کاربر
- نوع عملیات
- مدل
- رکورد
- مقدار قبلی
- مقدار جدید
- تاریخ
- ساعت
- IP (در صورت کاربرد)

| مورد | مقدار |
|------|-------|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند بررسی امنیت و مجوز دسترسی |

---

# ۱۱. یکپارچه‌سازی پیامک

| مورد | مقدار |
|------|-------|
| سرویس‌دهنده | Kavenegar |
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند پیکربندی Production و تأیید End-to-End |

**موارد استفاده:**

- تأیید موبایل
- تأیید ثبت‌نام
- ثبت سفارش
- تأیید سفارش
- رد سفارش
- پرداخت موفق
- تغییر وضعیت ترکینگ
- اعلان‌های مهم سیستم

---

# ۱۲. سخت‌سازی Production

## ۱۲.۱ امنیت

| مورد | وضعیت |
|------|--------|
| حذف / چرخش اسکریت‌های افشاشده | ⏳ |
| بررسی نحوهٔ نگهداری 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 |

## ۱۲.۲ یکپارچگی مالی

| مورد | وضعیت |
|------|--------|
| حفاظت از همزمانی کیف پول | ✅ `lockForUpdate()` در `CustomerCreditService::settle()` |
| یکتایی پرداخت (Idempotency) | ✅ race condition اصلاح شد |
| منطق مصرف کد تخفیف | ⏳ |
| دقت مبلغ و ارز | ✅ cast با `decimal:2` |
| یکپارچگی بدهی چندارزی | ✅ بدهی به همان ارز ثبت می‌شود، نه معادل ریالی |

> ✅ **انجام شد (۲۰۲۶-۱۰-۰۳):** تغییر نرخ ارز فقط از منوی «نرخ ارز» (تاریخچه + گردش تأیید + به‌روزرسانی از API) انجام می‌شود. فیلدهای مستقیم نرخ در «تنظیمات سیستم» حذف و به نمایش فقط‌خواندنی تبدیل شدند.

## ۱۲.۳ اپلیکیشن

| مورد | وضعیت |
|------|--------|
| بازبینی فلوی قدیمی سفارش | ⏳ |
| مدیریت خطاها | ⏳ |
| لاگ Production | ⏳ |
| پیکربندی Cache / OPcache | ⏳ |
| نسخه‌بندی Assetها | ⏳ |

---

# ۱۳. تست پذیرش End-to-End

## ۱۳.۱ مشتری

- [ ] ثبت‌نام
- [ ] تأیید موبایل
- [ ] ورود
- [ ] ثبت سفارش Export
- [ ] ثبت سفارش Import
- [ ] مشاهدهٔ سفارش
- [ ] انتظار برای تأیید
- [ ] دریافت اسناد
- [ ] دانلود اسناد
- [ ] آپلود اسناد امضاشده
- [ ] دریافت تأیید
- [ ] پرداخت با کیف پول
- [ ] پرداخت آنلاین
- [ ] مشاهدهٔ موجودی
- [ ] مشاهدهٔ تراکنش‌ها
- [ ] مشاهدهٔ ترکینگ
- [ ] دریافت اعلان‌ها

## ۱۳.۲ کارمند

- [ ] مشاهدهٔ سفارش‌ها
- [ ] تأیید سفارش
- [ ] رد سفارش
- [ ] آپلود تعهدنامه
- [ ] بررسی اسناد مشتری
- [ ] تکمیل چک‌لیست
- [ ] به‌روزرسانی مرسوله
- [ ] ایمپورت ترکینگ
- [ ] مشاهدهٔ وضعیت مالی مشتری
- [ ] مشاهدهٔ سفارش‌های مشتری
- [ ] بازبینی Audit Log

## ۱۳.۳ مدیر / مدیر کل

- [ ] بازبینی مالی مشتری
- [ ] اعطای اعتبار
- [ ] ویرایش اعتبار
- [ ] بازبینی Audit
- [ ] مشاهدهٔ تایم‌لاین مرسوله
- [ ] ویرایش داده‌های عملیاتی
- [ ] بازبینی فعالیت کارمندان

---

# ۱۴. دروازهٔ نهایی تحویل

پیش از انتشار در Production:

- [ ] همهٔ قابلیت‌های الزامی پیاده‌سازی شده‌اند
- [ ] باگ‌های بحرانی برطرف شده‌اند
- [ ] بازبینی امنیتی انجام شده
- [ ] فلوی پرداخت تست شده
- [ ] فلوی کیف پول تست شده
- [ ] فلوی Export تست شده
- [ ] فلوی Import تست شده
- [ ] PDFها تأیید شده‌اند
- [ ] پیامک تست شده
- [ ] ایمپورت ترکینگ تست شده
- [ ] بکاپ بررسی شده
- [ ] محیط Production بررسی شده
- [ ] تست پذیرش کارفرما (UAT) انجام شده

---

# ۱۵. خلاصهٔ وضعیت تحویل

**وضعیت فعلی:** آماده برای دیپلوی (۹۵٪ تکمیل)

**آخرین کامیت بازبینی‌شده:** ۲۰۲۶-۱۰-۰۴ — شامل بازطراحی PDF، صفحهٔ وضعیت مالی مشتری، Rate Limiting و سیستم اعتبار چندارزی کامل.

## ۱۵.۱ تکمیل‌شده در این دوره

- [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] پاک‌سازی کد (حذف فایل‌های تستی، تأیید تمیزی کد)

## ۱۵.۲ باقی‌مانده

- [ ] i18n (موکول به زمان دیپلوی)
- [ ] تست نهایی UAT کارفرما
- [ ] دیپلوی روی سرور Production
- [ ] سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما — موکول به آینده)

---

> **نکتهٔ نگهداری:** این فایل باید در طول تحویل پروژه به‌روزرسانی شود. این فایل فقط برای وضعیت تحویل مشتری است و نباید به مستندات معماری یا Roadmap محصول تبدیل شود.