ifnex/CLIENT_DELIVERY.md
Kazem Alghasi 6c745ea8f8 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
2026-10-04 03:17:35 +03:30

534 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

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