=== Valabi Retention ===
Contributors: valabi
Tags: woocommerce, abandoned cart, sms, kavenegar, retention, persian, rtl
Requires at least: 5.8
Tested up to: 6.7
Requires PHP: 7.4
WC requires at least: 6.0
WC tested up to: 9.4
Stable tag: 0.14.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

ابزار بازگردانی مشتریان والابی — یادآور سبد رهاشده با پیامک کاوه‌نگار و کوپن‌های اختصاصی بازگشت.

== Description ==

والابی ریتنشن به فروشگاه‌های ووکامرس کمک می‌کند مشتریانی را که سبد خرید خود را رها کرده‌اند با پیامک یادآوری و کد تخفیف اختصاصی برگرداند.

ویژگی‌ها:

* ردیابی سبدهای کاربران واردشده و مهمان‌ها
* گرفتن شماره موبایل مهمان‌ها در صفحه سبد
* ارسال پیامک از طریق کاوه‌نگار
* ساخت خودکار کوپن یک‌بارمصرف برای هر سبد
* لینک بازگردانی که سبد را در مرورگر مشتری بازسازی می‌کند
* داشبورد آمار با شمارش ردیابی، رهاسازی، بازیافت و درآمد

این افزونه هیچ داده‌ای را به سرور بیرونی غیر از درگاه پیامکی که خودتان پیکربندی می‌کنید ارسال نمی‌کند.

== Requirements ==

* WordPress 5.8+
* WooCommerce 6.0+ (Action Scheduler is bundled with WooCommerce; no extra install needed)
* PHP 7.4+
* یک حساب کاوه‌نگار با کلید API و شماره فرستنده فعال

== Installation ==

1. فایل افزونه را در پوشه `wp-content/plugins/valabi-retention/` قرار دهید.
2. در پیشخوان وردپرس به افزونه‌ها رفته و «والابی ریتنشن» را فعال کنید.
3. به منوی «والابی ریتنشن → تنظیمات» بروید و کلید API و شماره فرستنده کاوه‌نگار را وارد کنید.
4. از همان صفحه با دکمه «ارسال پیامک آزمایشی» اتصال را آزمایش کنید.

== Frequently Asked Questions ==

= چه زمانی سبد رهاشده محسوب می‌شود؟ =

به‌صورت پیش‌فرض پس از ۳۰ دقیقه بی‌فعالیتی، اما در صفحه تنظیمات قابل تغییر است.

= آیا برای مهمان‌ها هم کار می‌کند؟ =

بله، در صورت گرفتن شماره موبایل آن‌ها در صفحه سبد.

= آیا داده‌ای به جایی ارسال می‌شود؟ =

خیر. تنها ارتباط بیرونی، تماس HTTP با درگاه پیامکی شما (کاوه‌نگار) است.

== Changelog ==

= 0.14.1 =
* یکدست‌سازی متن‌ها برای دو درگاه: عنوان بخش پیامک، هشدار اعتبار کم نوار مدیریت، و راهنمای تنظیمات دیگر فقط به کاوه‌نگار اشاره نمی‌کنند و درگاه فعال را نشان می‌دهند.
* بهینه‌سازی: برای درگاه‌هایی که بررسی وضعیت تحویل ندارند (آی‌پی‌پنل) دیگر job بی‌مصرف بررسی تحویل در Action Scheduler ساخته نمی‌شود.

= 0.14.0 =
* افزودن درگاه دوم پیامک «آی‌پی‌پنل» (Edge API) در کنار کاوه‌نگار: در «تنظیمات» می‌توانید درگاه فعال را انتخاب و کلید API و شماره فرستنده آی‌پی‌پنل را وارد کنید.
* پشتیبانی از الگوهای آی‌پی‌پنل با «متغیرهای نام‌دار»: در ویرایش هر قالب می‌توانید متغیرهای نام‌دار الگو را به‌صورت «نام:مقدار» نگاشت کنید (کاوه‌نگار همچنان از جایگاه‌های token… استفاده می‌کند).
* صفحهٔ «وضعیت و اعتبار» اکنون اعتبار درگاه فعال را نشان می‌دهد (کاوه‌نگار یا آی‌پی‌پنل) و عنوان/متن‌ها بر اساس درگاه انتخابی نمایش داده می‌شوند.
* آزمایش زندهٔ الگو در تنظیمات با هر دو درگاه کار می‌کند.

= 0.13.0 =
* حذف سیستم لایسنس: افزونه دیگر به کلید نیاز ندارد و همیشه فعال است (بدون گیت، بدون صفحهٔ لایسنس). به‌جای آن یک «ضربان» فنی روزانه و بی‌صدا برای آمار استفاده ارسال می‌شود (آدرس سایت و نسخهٔ افزونه/وردپرس/ووکامرس/PHP)؛ بدون رابط کاربری و بدون اثر بر کارکرد سایت. با ثابت VALABI_RETENTION_TELEMETRY_OFF یا فیلتر valabi_retention_telemetry_enabled قابل خاموش‌کردن است.

= 0.12.4 =
* رفع باگ فعال‌سازی لایسنس: پس از ثبت کلید، دیگر صفحهٔ «دسترسی ندارید» نمایش داده نمی‌شود و کاربر به داشبورد افزونه هدایت می‌شود. منوی «لایسنس» اکنون به‌جای ابتدای فهرست، در انتهای زیرمنوهای افزونه قرار می‌گیرد.
* رفع خطای ۴۰۴ در فرانت‌اند پس از فعال‌سازی (لینک بازگردانی سبد): قوانین بازنویسی (rewrite rules) یک‌بار به‌صورت خودکار بازنشانی می‌شوند.

= 0.12.3 =
* افزوده شدن سیستم لایسنس والابی: افزونه با کلید معتبر فعال می‌شود و بدون آن به‌صورت ایمن غیرفعال می‌ماند (فروشگاه آسیبی نمی‌بیند). صفحهٔ «لایسنس»، بررسی روزانه، و بازهٔ مهلت در صورت در دسترس نبودن سرور. کلید لایسنس هرگز به‌صورت کامل نمایش داده نمی‌شود (فقط نسخهٔ ماسک‌شده) و نشانی سرور اعتبارسنجی نمایش داده نمی‌شود.

= 0.12.0 =
* بررسی وضعیت تحویل کاوه‌نگار ۵ دقیقه پس از ارسال: اگر کاوه‌نگار نتیجه قطعی برگرداند (تحویل/عدم تحویل) ستون جدید delivery_status به‌روزرسانی می‌شود؛ اگر هنوز در صف باشد، وضعیت «ارسال‌شده» دست نخورده می‌ماند.
* رهگیری استفاده از کوپن: ستون coupon_code روی هر پیامک ذخیره می‌شود و هنگام ثبت سفارش بازگشتی، کوپن استفاده‌شده به‌عنوان «استفاده‌شده» علامت می‌خورد — آمار «کوپن استفاده‌شده» در کارت هر قالب.
* محدودیت ارسال هر قالب در هر سبد: یک قالب هرگز برای یک سبد بیش از یک بار ارسال نمی‌شود (محافظ نسبت به چرخه‌های re-abandon).
* عملیات گروهی روی لاگ پیامک‌ها: انتخاب با checkbox + dropdown برای حذف، تلاش مجدد ناموفق‌ها، یا لغو ارسال‌های در صف.
* ستون «تحویل» در لاگ پیامک‌ها + ستون‌های جدید (delivery_status، coupon_code، coupon_redeemed) در خروجی CSV.
* schema → v5 + اکشن جدید valabi_retention_check_delivery در Action Scheduler.

= 0.11.0 =
* اصلاح انتساب بازگشت: سبدی به‌عنوان «بازیافت با SMS» شناخته می‌شود فقط اگر مشتری روی لینک بازگردانی کلیک کرده باشد و سپس سفارش ثبت کند.
* سفارش‌هایی که بدون کلیک روی لینک ثبت می‌شوند به وضعیت جدید `self_recovered` (بازگشت بدون کلیک) منتقل می‌شوند — در گزارش‌ها و کارت‌های داشبورد جداگانه دیده می‌شوند.
* «درآمد بازیافت‌شده» داشبورد و نرخ تبدیل هر قالب فقط از روی بازگشت‌های واقعی (با کلیک) محاسبه می‌شود.
* اکشن جدید `valabi_retention_cart_self_recovered` برای ادغام با ابزارهای تحلیل خارجی — اکشن قدیمی `valabi_retention_cart_recovered` فقط برای بازگشت‌های انتسابی فعال می‌شود.

= 0.10.1 =
* رفع جهت حرکت دکمه toggle: knob به‌جای خارج شدن از مسیر، از یک سمت track به سمت دیگر می‌خزد (هم در RTL و هم LTR).

= 0.10.0 =
* تلاش مجدد خودکار در صورت خطای ارسال (پیش‌فرض ۲ بار با فاصله ۵ دقیقه) — تلاش‌های مجدد محدودیت روزانه شماره را نادیده می‌گیرند.
* بنر قرمز در پیشخوان وقتی همه تلاش‌ها ناموفق بمانند: «سامانه پیامک کار نمی‌کند» — با اولین ارسال موفق خودکار پاک می‌شود.
* تشخیص مشتری جدید / بازگشتی بر اساس داشتن سفارش قبلی (HPOS-aware، با کش یک‌ساعته).
* فیلد «مخاطب» در ویرایشگر قالب: ارسال فقط به مشتری جدید، فقط بازگشتی، یا همه.
* صفحه «سبدهای امروز»: لیست سبدهای ایجادشده از ابتدای امروز (تهران) با شمار کالاها، نشان «بازگشتی/جدید» و آخرین فعالیت. سقف ۲۰۰ ردیف، lookup گروهی برای امن بودن روی هاست اشتراکی.
* ردیابی تعداد کلیک روی لینک بازگردانی — ستون جدید «کلیک» در لاگ پیامک‌ها همراه با زمان اولین کلیک.
* ساعت سکوت (پیش‌فرض ۲۳ تا ۸ به وقت تهران، قابل تنظیم) — ارسال‌های شب خودکار به صبح موکول می‌شوند.
* بخش «والابی ریتنشن» در پروفایل کاربر: تیک «پیامک یادآور برای من ارسال نشود» با احترام کامل در مسیر ارسال.
* تست زنده الگوی Lookup در صفحه تنظیمات: قالب را انتخاب کنید، شماره را وارد کنید، پیامک واقعی با همان متغیرها و الگو ارسال می‌شود (با داده‌های نمونه).
* محدودیت روزانه فقط بر مبنای ارسال‌های موفق محاسبه می‌شود (تلاش‌های ناموفق به سهمیه شمرده نمی‌شوند).
* schema → v4: ستون audience روی templates، recovery_click_count روی carts، ایندکس created_at برای پرس‌وجوی «سبدهای امروز».

= 0.9.2 =
* رفع خطای fatal در صفحه «وضعیت و اعتبار» — حذف ارجاع باقیمانده به ثابت قدیمی AJAX_TOGGLE_AUTO.
* اصلاح محاسبه درآمد بازیافت‌شده: وقتی سفارش لینک‌شده در وضعیت پرداخت‌نشده/لغو/سفارشی است، به جای صفر دانستن، از مبلغ سبد ذخیره‌شده به‌عنوان مقدار جایگزین استفاده می‌شود.
* بازطراحی کارت درآمد بازیافت‌شده: فونت کوچک‌تر برای جا گرفتن عدد، واحد ارز به‌صورت متن کوچک‌تر در کنار رقم.

= 0.9.1 =
* افزایش ظرفیت تاریخچه بررسی‌های API کاوه‌نگار از ۲۰ به ۲۰۰ ردیف برای دیدِ بلندمدت‌تر.

= 0.9.0 =
* بازطراحی داشبورد: کارت‌های آماری بزرگ‌تر با گرادینت اختصاصی برای هر متریک، گرید واکنش‌گرا که فضای افقی را پر می‌کند (در صفحه‌های پهن، شش کارت در یک ردیف؛ کوچک‌تر، در گرید سه‌تایی).
* پیاده‌سازی سیستم طراحی مشترک «والابی» در همه صفحه‌های مدیریت — همان حس‌وحال صفحه فاکتورها با لهجه گرم نهادی (Persian Institutional) و رنگ شاخص زرشکی.
* رفع باگ سوییچ بررسی خودکار اعتبار: ارسال فرم به admin-post.php به‌جای AJAX، فراخوانی مستقیم Action Scheduler و یک بررسی فوری همراه با فعال‌سازی — تا کاربر نتیجه را بلافاصله در لاگ ببیند.

= 0.8.0 =
* محدودیت ارسال به ازای هر شماره: اگر در بازه تنظیم‌شده (به‌صورت پیش‌فرض ۷ روز) بیشتر از N پیامک (پیش‌فرض ۳) به یک شماره ارسال شده باشد، ارسال بعدی به‌صورت rate_limited در لاگ ثبت می‌شود و پیامک واقعی ارسال نمی‌شود. حساب مهمان و کاربر بر اساس شماره یکسان شمرده می‌شوند.
* فیلتر «محدود (تکرار)» در گزارش پیامک‌ها و اکشن valabi_retention_send_rate_limited برای ادغام‌های خارجی.
* تغییردهی فعال/غیرفعال بررسی خودکار اعتبار از صفحه «وضعیت و اعتبار» — با سوییچ بصری، نمایش «بررسی بعدی: X دقیقه دیگر»، بدون نیاز به بارگذاری مجدد صفحه.

= 0.7.0 =
* ادغام سبد مهمان با حساب کاربری در زمان ورود (بر اساس شماره موبایل).
* صفحه «ابزارها» با پاکسازی سبدهای منقضی، حذف لاگ پیامک‌های قدیمی، اجرای دستی اسکن و پاک کردن کش درآمد.
* اعتبارسنجی خودکار کلید API کاوه‌نگار پس از ذخیره تنظیمات — نمایش نتیجه به‌صورت نوار سبز/قرمز.
* آمار هر قالب: تعداد ارسال، تعداد بازگشت، نرخ تبدیل، تعداد ناموفق.
* صفحه «راهنما» با مستندات کامل (راه‌اندازی الگوی کاوه‌نگار، توضیح متغیرها و جایگاه‌های token، عیب‌یابی، هوک‌های توسعه‌دهنده).
* اکشن‌های valabi_retention_send_succeeded و valabi_retention_send_failed برای ادغام با Sentry/Slack/سیستم‌های لاگ خارجی.

= 0.6.0 =
* درآمد واقعی بازیافت‌شده از روی جمع سفارش‌های واقعی محاسبه می‌شود (پس از کسر استرداد)؛ کش ۵ دقیقه‌ای.
* نمایش تاریخ شمسی به‌صورت خودکار وقتی locale سایت fa_IR است (با ارقام فارسی).
* خروجی CSV از صفحه گزارش‌ها (هر دو تب) با BOM یونیکد برای اکسل.
* محدود کردن نگه‌داری تاریخچه Action Scheduler به ۳۰ روز (فقط کاهش، هرگز افزایش).
* راه‌اندازی PHPUnit + Brain Monkey با تست‌های اولیه برای تقویم شمسی و نرمال‌سازی شماره.

= 0.5.0 =
* رفع باگ: نگه‌داشتن کاراکترهای URL در token10/token20 (لینک بازگردانی به‌درستی به مشتری می‌رسد).
* ثبت زمان کلیک روی لینک بازگردانی (ستون recovery_clicked_at) برای ارزیابی عملکرد قالب‌ها.
* صفحه «خوش‌برگشتید» در سبد بعد از کلیک روی لینک یادآور — همراه با خلاصه سبد و کد تخفیف.
* حالت آزمایشی (Dry-run): ارسال‌ها فقط در لاگ ثبت می‌شوند، تماس با کاوه‌نگار انجام نمی‌شود.
* هشدار اعتبار کم در نوار مدیریت با آستانه قابل تنظیم.
* بررسی خودکار اعتبار کاوه‌نگار هر ۵ دقیقه (قابل غیرفعال‌سازی).
* صفحه جزئیات هر سبد: خط‌زمانی رویدادها، فهرست محصولات، تاریخچه پیامک‌ها.
* دکمه «ارسال الآن» برای ارسال دستی هر قالب فعال به یک سبد خاص.
* ارتقای schema به نسخه ۳ (افزودن recovery_clicked_at) — به‌صورت خودکار با dbDelta روی نصب‌های قبلی اعمال می‌شود.

= 0.4.0 =
* پشتیبانی از الگوهای Lookup کاوه‌نگار: امکان وارد کردن نام الگوی تأییدشده در کاوه‌نگار و نگاشت متغیرها به token / token2 / token3 / token10 / token20.
* صفحه «قالب‌های پیامک» برای ویرایش قالب‌ها، تعیین الگو، تنظیم تأخیر ارسال و کوپن مرتبط.
* صفحه «گزارش‌ها» با نمایش تاریخچه سبدها (ردیابی، رهاسازی، بازگردانی، انقضا) و لاگ کامل پیامک‌ها (موفق و ناموفق).

= 0.3.0 =
* افزودن صفحه «وضعیت و اعتبار کاوه‌نگار» با نمایش اعتبار باقی‌مانده، تاریخ انقضا، نوع حساب و دکمه بررسی دوباره.
* ثبت تاریخچه ۲۰ بررسی اخیر (دستی/خودکار) با وضعیت موفق یا خطا.

= 0.2.0 =
* افزودن سیستم به‌روزرسانی خودکار (PUC v5.6) با endpoint اختصاصی mobodel.ir و سقف زمانی ۱۰ ثانیه برای درخواست بررسی نسخه.

= 0.1.0 =
* نسخه اولیه: ردیابی سبد، تشخیص رهاسازی، ارسال پیامک کاوه‌نگار، ساخت کوپن، لینک بازگردانی، داشبورد آمار.
