# یادداشت انتشار (Release Notes) — نسخه ۱.۷.۱

نسخه ۱.۶.۰ تجربهٔ تلگرامی تمیزتر و آمار صادقانه‌تری ارائه می‌کند: راهنماهای موقت ادمین پاک می‌شوند، سؤال‌ها با متن کامل گزینه‌ها و دکمه‌های عددی inline نمایش داده می‌شوند، Broadcast فقط دکمه URL امن دارد، فیلترها test-first هستند، اسلاگ/گیت/کانال‌ها قابل ویرایش‌اند، محتوای فرعی چندآیتمی اضافه شده و reminder/update/downgrade سخت‌گیری بیشتری دارند. جزئیات کامل در `CHANGELOG.md` است.

## یادداشت تاریخی نسخه ۱.۴.۰

## نسخه

**v1.4.0-updatepack** — بسته به‌روزرسانی کامل (Update Pack PART1-4) روی
فاز ۷ MVP. تمام قابلیت‌های v1.3.0 حفظ شده‌اند؛ این نسخه علاوه بر آن‌ها،
تجربه دانش‌آموز را بازسازی کرده و چند قابلیت عملیاتی مهم (پیام همگانی،
لینک‌های قابل چرخش، به‌روزرسانی از داخل ربات) را اضافه کرده است.

## مهم‌ترین تغییرات نسبت به v1.3.0

- **حذف کامل الزام عضویت در کانال از مسیر دانش‌آموز**: از این نسخه به
  بعد، عضویت در کانال هرگز نمایش نتیجه را مسدود، به تأخیر یا دوباره
  درخواست نمی‌کند. بررسی عضویت فقط برای آمار داخلی (چند نفر بعد از
  دیدن نتیجه واقعاً عضو شدند) ثبت می‌شود، هرگز جلوی کاربر را نمی‌گیرد.
- **گزینه‌های آزمون اکنون دکمه‌های شماره‌دار متنی هستند** («۱) گزینه...»)
  به‌جای دکمه‌های شیشه‌ای زیر پیام — حس طبیعی‌تر چت، همراه با نوار
  پیشرفت («سوال ۲ از ۵») و محافظت کامل در برابر فشردن دکمه قدیمی/نامعتبر.
- **شمارنده‌های آماری صادقانه**: شروع/تکمیل منحصربه‌فرد هر آزمون بر اساس
  «هر کاربر یک‌بار» شمرده می‌شود، نه هر تلاش — تلاش مجدد همان کاربر
  دیگر آمار را دستکاری نمی‌کند.
- **پیام همگانی (Broadcast)** — این محدودیت نسخه قبل رفع شد: اکنون
  می‌توانید به همه کاربران یا یک بخش مشخص، پیام گروهی (همراه با دکمه
  اختیاری) با سرعت امن (رعایت محدودیت‌های تلگرام) ارسال کنید، با پیشرفت
  زنده و امکان لغو.
- **لینک‌های کمپین قابل چرخش**: اگر یک لینک اختصاصی جایی درز کرد یا
  می‌خواهید بدون از دست دادن آمار قبلی، لینک جدید بسازید، می‌توانید
  لینک قدیمی را غیرفعال و لینک جدید صادر کنید — تاریخچه و آمار قبلی
  کاملاً حفظ می‌شود.
- **به‌روزرسانی و بازگشت نسخه از داخل ربات**: مدیر ارشد می‌تواند یک
  فایل ZIP به‌روزرسانی را مستقیماً در تلگرام آپلود کند؛ ربات پیش از هر
  تغییری از کد و دیتابیس نسخه پشتیبان می‌گیرد و در صورت نیاز امکان
  بازگشت به نسخه قبلی وجود دارد.
- **کنسول امن تغییر تنظیمات حساس**: تغییر توکن ربات یا اطلاعات دیتابیس
  دیگر نیازی به دسترسی مستقیم به فایل‌های سرور ندارد — یک لینک یک‌بارمصرف
  و امن از داخل ربات صادر می‌شود.
- **کیبورد ثابت مدیر**: با هر بار /start مدیر، یک کیبورد ثابت با
  دسترسی سریع به همه بخش‌های مدیریتی نمایش داده می‌شود.
- **سخت‌سازی نصب‌کننده**: پس از نصب موفق، فایل نصب‌کننده و هرگونه مقدار
  پیش‌فرض حساس به‌طور خودکار از روی سرور پاک می‌شوند تا برای همیشه در
  دسترس عموم نمانند.

## قابلیت‌های کامل این نسخه

### مسیر دانش‌آموز
- لینک اختصاصی آزمون → مستقیم سوال اول (بدون هیچ متن معرفی)
- سوالات فقط متنی + دکمه‌های شماره‌دار متنی (بدون دکمه شیشه‌ای) + نوار پیشرفت
- شاخه‌بندی مسیر سوالات (next/jump/end)
- امتیازدهی خودکار و انتخاب نتیجه شخصی‌سازی‌شده (تک‌نتیجه یا دو‌نتیجه نزدیک، همراه متن مقدمه اختیاری برای حالت دونتیجه‌ای)
- نتیجه: متن تحلیل + ویس + فایل، هرکدام کاملاً اختیاری، بدون جای خالی
- دکمه CTA قابل تنظیم (فقط شیشه‌ای، فقط متنی، یا هردو)
- عضویت کانال فقط برای آمار داخلی ثبت می‌شود — هرگز مسدودکننده نیست
- ثبت آمار کامل قیف (شروع/تکمیل منحصربه‌فرد، افت هر سوال، عضویت)

### مسیر ادمین — ساخت آزمون (از داخل تلگرام)
- ساخت آزمون فقط با عنوان (اسلاگ خودکار)
- پروفایل‌ها فقط با عنوان فارسی (کد انگلیسی خودکار)
- سوالات فقط متنی (بدون رسانه)
- گزینه‌ها + شاخه‌بندی مسیر
- امتیازدهی زنده با دکمه‌های +/- (کف صفر)، ذخیره دومرحله‌ای (draft → ثبت)
- ویرایشگر نتیجه: متن/ویس/فایل/CTA، همه اختیاری و مستقل
- دروازه فعال‌سازی هوشمند (قبل از انتشار، ساختار آزمون را کامل بررسی می‌کند)
- کتابخانه فایل مستقل از نتایج
- **جدید**: پیوند مستقیم آزمون به کمپین، لینک‌های اختصاصی قابل چرخش

### مسیر ادمین — عملیات (Ops)
- 👥 **کاربران**: لیست صفحه‌بندی‌شده، جستجو، جزئیات، بن/آنبن، ارسال پیام مستقیم، **گفت‌وگوی خصوصی دوطرفه (Relay)**
- 📣 **کمپین‌ها**: ساخت، لینک‌های اختصاصی قابل چرخش، آمار جذب هر کمپین
- 📨 **پیام همگانی (جدید)**: ارسال گروهی امن با دکمه اختیاری، پیشرفت زنده، قابل لغو
- 📈 **آنالیتیکس**: گزارش کلی/هر آزمون/هر کمپین با بازه‌های زمانی ۲۴ ساعت/۷ روز/۳۰ روز/کل + افت هر سوال
- 🗜 **پشتیبان‌گیری**: بکاپ کامل دیتابیس با یک تپ، بازیابی امن با تأیید دومرحله‌ای
- 🔄 **به‌روزرسانی/بازگشت نسخه (جدید)**: آپلود ZIP از داخل تلگرام، بکاپ خودکار پیش از اعمال، امکان بازگشت
- 🔐 **کنسول امن تنظیمات هسته (جدید)**: تغییر توکن/دیتابیس/افزودن ادمین از طریق لینک یک‌بارمصرف
- 📋 **لاگ‌ها**: مشاهده و دریافت مستقیم فایل لاگ از داخل تلگرام
- 🩺 **سلامت سیستم**: چک‌لیست خودکار سلامت کل سیستم (شامل بررسی خودکار افشای نصب‌کننده)

### زیرساخت
- سیستم لاگ تشخیصی مرکزی (برای عیب‌یابی سریع، بدون نیاز به SSH)
- نصب‌کننده فارسی کامل، قفل‌شونده و خودپاک‌کننده پس از نصب موفق
- امنیت چندلایه (وبهوک، ادمین، IDOR، rate limit، redaction لاگ، CSRF در کنسول امن)

## محدودیت‌های شناخته‌شده (صادقانه)

- بدون پنل مدیریت گرافیکی وب (فقط از داخل تلگرام) — طبق طراحی محصول
- ردیابی کلیک روی دکمه CTA هنوز پیاده‌سازی نشده (فقط لینک مستقیم است)
- بازیابی از بکاپ روی MySQL از نظر فنی «تقریباً اتمیک» است، نه ۱۰۰٪ تضمینی در صورت قطعی وسط عملیات — پیشنهاد می‌شود اول روی نسخه تستی امتحان شود
- انتساب «عضویت پس از تکمیل آزمون» یک مدل تقریبی و شفاف است (بر اساس آخرین آزمونی که کاربر در بازه زمانی قابل تنظیم تکمیل کرده)، نه ردیابی ۱۰۰٪ دقیق — چون عضویت یک رویداد سطح کانال است، نه سطح آزمون
- به‌روزرسانی از داخل ربات، swap فایل‌ها را اتمیک انجام می‌دهد اما در صورت قطع برق/سرور دقیقاً وسط نوشتن فایل‌ها، ممکن است نیاز به تکمیل دستی باشد (بکاپ کامل همیشه پیش از اعمال گرفته می‌شود)

## نحوه نصب سریع

1. فایل zip را روی هاست cPanel آپلود و استخراج کنید.
2. Document Root را روی پوشه `public/` تنظیم کنید.
3. یک دیتابیس MySQL بسازید.
4. آدرس `https://yourdomain.com/install.php` را باز کرده و مراحل را
   کامل کنید.
5. پس از نصب موفق، فایل `install.php` و هرگونه فایل مقادیر پیش‌فرض
   حساس به‌طور خودکار پاک می‌شوند — نیازی به کار دستی نیست.

راهنمای کامل قدم‌به‌قدم: `docs/DEPLOY_CPANEL_FA.md`

## مستندات مهم برای شروع

- `docs/DEPLOY_CPANEL_FA.md` — نصب قدم‌به‌قدم
- `docs/ADMIN_GUIDE.md` — راهنمای ساخت آزمون + پیام همگانی + لینک‌های کمپین + به‌روزرسانی + کنسول امن
- `docs/USER_ACCEPTANCE_CHECKLIST_FA.md` — چک‌لیست پذیرش
- `docs/TROUBLESHOOTING_FA.md` — رفع مشکلات رایج
- `docs/TELEGRAM_LIMITS_AND_SCALE_FA.md` — محدودیت‌های تلگرام و مقیاس‌پذیری
- `docs/AGENT_HANDOFF.md` — برای توسعه‌دهنده/ایجنت بعدی

## تست و کیفیت

این نسخه با ۱۴ فایل تست خودکار (بیش از ۳۰۰ assertion واقعی، نه نمایشی)
روی یک محیط کامل (دیتابیس واقعی + شبیه‌ساز API تلگرام + سرور HTTP واقعی)
تأیید شده است. پنج باگ واقعی در طول توسعه این بسته پیدا و رفع شدند
(جزئیات کامل در `docs/CHANGELOG.md`)، از جمله یک باگ در خود منطق
ردیابی عضویت که تا پیش از تست جامع، مخفی مانده بود.