6c745ea8f8
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
20 KiB
IFNEX — چک‌لیست تحویل به مشتری
وضعیت: آماده برای دیپلوی (۹۵٪ تکمیل) فاز جاری: فاز ۳.۶ — اصلاحات جلسهٔ کارفرما تاریخ آخرین به‌روزرسانی: ۲۰۲۶-۱۰-۰۴ مخزن: git.vernahost.ir/gitmodir110/ifnex
⚠️ این فایل فقط برای مدیریت تعهدات، تست و تحویل نسخهٔ فعلی مشتری است و جایگزین
AGENT.mdیاIFNEX_Roadmap.mdنیست.
راهنمای وضعیت‌ها
| نشان | معنی |
|---|---|
| ✅ | تکمیل‌شده |
| 🟡 | پیاده‌سازی‌شده — نیازمند تأیید نهایی |
| ⏳ | در انتظار |
| 🔴 | مسدود |
| ❌ | پیاده‌سازی‌نشده |
۱. فرانت‌اند و صفحهٔ اصلی
۱.۱ هدایت دکمهٔ ردیابی مرسوله
الزام مشتری: در بخش Hero صفحهٔ اصلی وردپرس، دکمهٔ «ردیابی مرسوله» کاربر را به صفحهٔ اختصاصی Tracking هدایت کند.
| مورد | مقدار |
|---|---|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |
| فایل‌ها | 03_WordPress/wp-content/themes/ifnex/03_WordPress/wp-content/plugins/ifnex-bridge/ |
تست پذیرش:
- کلیک روی دکمهٔ CTA
- ریدایرکت صحیح انجام می‌شود
- URL مقصد صحیح است
- صفحهٔ Tracking درست نمایش داده می‌شود
- رفتار در حالت Login و Guest بررسی شد
۱.۲ فرم ثبت سفارش چندمرحله‌ای
الزام مشتری: پس از تکمیل مرحلهٔ اول، مرحلهٔ دوم بدون خطا Load شود.
| مورد | مقدار |
|---|---|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |
| باگ تاریخی | بسته‌نبودن یک div در فایل shortcodes.php |
| فایل‌ها | includes/shortcodes.phpassets/js/ifnex-order-form.js |
تست پذیرش:
- حرکت رو به جلو بین مراحل
- حرکت رو به عقب بین مراحل
- اعتبارسنجی فرم در هر مرحله
- حفظ اطلاعات مراحل قبلی
- Console مرورگر بدون Error
- رفتار Export و Import بررسی شد
۲. داشبورد مشتری و وضعیت مالی
۲.۱ مانده حساب مشتری
الزام مشتری: در داشبورد مشتری، علاوه بر موجودی کیف پول و سفارش‌ها، مانده حساب نیز نمایش داده شود.
فرمول مورد انتظار:
Account Balance = Wallet Balance − Outstanding Approved Obligations
| مورد | مقدار |
|---|---|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید نهایی |
تست پذیرش:
- کیف پول مثبت
- مشتری بدون بدهی
- مشتری دارای بدهی
- مشتری با چند سفارش تأییدشده ولی پرداخت‌نشده
- نمایش صحیح ارز
- بدهی چندارزی به مبلغ ریالی اشتباه تبدیل نمی‌شود
۳. تأیید سفارش پیش از پرداخت
الزام اصلی: مشتری بلافاصله پس از ثبت سفارش نباید وارد درگاه پرداخت شود.
۳.۱ فلوی عمومی
Create Order
→ Pending Approval
→ Staff Review
→ Approved
→ Documents / Commitment Verification
→ Payment Enabled
→ Wallet OR Online Payment
→ Paid
→ Processed
| مورد | مقدار |
|---|---|
| وضعیت | 🟡 پیاده‌سازی‌شده — نیازمند تأیید End-to-End |
۳.۲ سفارش Export
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
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 و سیستم اعتبار چندارزی کامل.
۱۵.۱ تکمیل‌شده در این دوره
- فلوی پذیرش End-to-End (کیف پول + درگاه پس از تأیید تعهدنامه)
- بازطراحی داشبورد و صفحهٔ Login (پنل Filament)
- بازطراحی PDFهای AWB، Invoice و Label (dompdf، چیدمان جدولی، navy + amber)
- صفحهٔ وضعیت مالی مشتری در پنل ادمین
- سیستم اعتبار چندارزی (درخواست ۹) — تکمیل End-to-End
- ویجت بدهی‌های ارزی تسویه‌نشده + badge ناوبری
- اصلاح race condition در تسویهٔ اعتبار
CreditsRelationManagerرویUserResource- Rate Limiting روی همهٔ endpointهای API (۶ لایه)
- چک‌لیست خودکار کارمند پس از تأیید سفارش (درخواست ۵)
- نمایش بدهی ارزی در پورتال مشتری وردپرس
- استایل‌دهی صفحهٔ پروفایل مشتری در وردپرس
- پاک‌سازی کد (حذف فایل‌های تستی، تأیید تمیزی کد)
۱۵.۲ باقی‌مانده
- i18n (موکول به زمان دیپلوی)
- تست نهایی UAT کارفرما
- دیپلوی روی سرور Production
- سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما — موکول به آینده)
نکتهٔ نگهداری: این فایل باید در طول تحویل پروژه به‌روزرسانی شود. این فایل فقط برای وضعیت تحویل مشتری است و نباید به مستندات معماری یا Roadmap محصول تبدیل شود.