تکمیل فاز ۳ و فاز ۴ + راهنمای نصب صفر تا صد — Telegram Bot Builder SaaS
=========================================================================
این پکیج شامل «کل پروژه ادغام‌شده» است: هسته اصلی (Full Core) + تکمیل فاز ۱/۲ + فاز ۳/۴ جدید،
همه در یک ساختار واحد. یعنی دیگر نیازی به آپلود چند ZIP جدا نیست؛ همین یک پوشه را آپلود کنید.

نصب صفر تا صد
--------------
۱) آماده‌سازی هاست
   - PHP 8.1+ با اکستنشن‌های: pdo_mysql, curl, mbstring, json, openssl
   - دیتابیس MySQL/MariaDB خالی بسازید (یوزر/پسورد را یادداشت کنید)
   - یک دامنه یا ساب‌دامنه با گواهی SSL معتبر (HTTPS اجباری است، تلگرام Webhook روی HTTP کار نمی‌کند)

۲) آپلود فایل‌ها
   - کل محتوای این پوشه را در روت هاست (یا ساب‌دامنه) آپلود کنید.
   - مطمئن شوید Document Root سرور روی پوشه public/ تنظیم است (نه روت پروژه). اگر امکان تنظیم
     DocumentRoot نیست، از .htaccess ریدایرکت به public/ استفاده کنید یا کل سایت را داخل public قرار دهید.

۳) اجرای Installer
   - آدرس /install را در مرورگر باز کنید (یا اگر پوشه install/ در روت است: /install/index.php).
   - اطلاعات دیتابیس (host, name, user, pass) را وارد کنید.
   - Installer به‌صورت خودکار همه فایل‌های database/migrations/*.sql (شامل 0005_phase3_phase4.sql
     جدید) را به ترتیب اجرا می‌کند و جدول‌های لازم را می‌سازد.
   - یک حساب Super Admin و اولین تنانت/کاربر SaaS را در همین مرحله بسازید.
   - بعد از اتمام موفق نصب، برای امنیت پوشه install/ را حذف یا rename کنید (مثلاً install_done/).

۴) تنظیم Cron (اجباری برای Broadcast، Automation تاخیری، انقضای اشتراک و ...)
   در پنل هاست (cPanel → Cron Jobs یا مشابه) یک Cron هر ۱ دقیقه اضافه کنید:
       * * * * * php /path/to/project/cron/worker.php >> /path/to/project/storage/cron.log 2>&1

۵) ورود به پنل
   - پنل کاربری (تنانت): /login یا /register برای ثبت‌نام صاحب ربات
   - پنل مدیریت کل سیستم (Super Admin): /admin

۶) اتصال و Webhook کردن اولین ربات — به بخش «وبهوک کردن ربات» در پایین همین فایل مراجعه کنید.

فایل‌های تغییر یافته / جدید نسبت به هسته اصلی
------------------------------------------------
- database/migrations/0005_phase3_phase4.sql   [جدید]  ستون‌های bot_id/department_id/updated_at
  روی tickets، ستون target_tag_id روی broadcasts، جدول جدید automation_queue (اکشن تاخیری)
- src/AI/AiClient.php                          [جدید]  کلاینت عمومی سازگار با OpenAI Chat Completions
- src/Http/routes_phase3_phase4.php            [جدید]  همه route های فاز ۳ و ۴
- src/Bot/UpdateHandler.php                    [جایگزین] اجرای واقعی Automation (Delay/Tag/Wallet/Notify)،
  دستور /ticket برای ثبت تیکت از داخل ربات، پاسخ خودکار AI Chatbot، ادامه گفتگو در تیکت باز
- bootstrap.php                                [جایگزین] ثبت AiClient
- cron/worker.php                              [جایگزین] پردازش صف Automation تاخیری + فعال‌سازی
  Broadcast های زمان‌بندی‌شده
- public/index.php                             [جایگزین] require فایل route جدید + مسیر عمومی
  Mini App (/app/{bot}/{slug}) + REST API (/api/v1/...)
- views/dashboard/index.php                    [جایگزین] لینک‌های منوی فاز ۳/۴
- views/management/broadcasts.php              [جایگزین] هدف‌گیری بر اساس Tag + زمان‌بندی ارسال
- views/management/automations.php, forms.php, form_fields.php, form_responses.php,
  tickets.php, ticket_view.php, notification_settings.php, notifications.php, analytics.php,
  api_keys.php, miniapp.php, templates.php, ai_settings.php, ai_knowledge.php, ai_generate.php   [جدید]

آنچه اضافه شد — فاز ۳ (Automation و پشتیبانی)
------------------------------------------------
- Automation Builder: ساخت قانون با Trigger (پیام/شروع ربات/...)، یک Condition ساده
  (برابر است با / شامل می‌شود) و چند Action در کنار هم (/automations)
- Trigger / Condition / Action: پیاده‌سازی واقعی در UpdateHandler روی هر پیام دریافتی از تلگرام
- Delay و Schedule: Action نوع «تاخیر» پیام را به جدول automation_queue می‌فرستد و
  cron/worker.php بعد از گذشت زمان تعیین‌شده آن را ارسال می‌کند
- Form Builder: ساخت فرم + فیلدهای دلخواه (متن/عدد/تلفن/ایمیل/انتخابی/فایل) روی هر ربات (/forms)
- Form Submission: نمایش پاسخ‌های ثبت‌شده هر فرم (/forms/responses)
- Ticket System: کاربر ربات با دستور «/ticket موضوع پیام» در تلگرام تیکت می‌سازد؛ ادمین از
  پنل (/tickets) پاسخ می‌دهد و پاسخ مستقیم در تلگرام برای کاربر ارسال می‌شود
- Notification System: تعریف قانون اعلان به‌ازای رویدادهای مهم (سفارش جدید، تیکت جدید و ...)
  با کانال «داخل پنل» یا «Webhook» (/notification-settings ، /notifications)
- Broadcast پیشرفته: هدف‌گیری بر اساس Tag کاربران + زمان‌بندی ارسال (Schedule)
- Analytics / User Analytics / Sales Analytics / Referral Analytics: یک داشبورد واحد
  با آمار رشد کاربران، فروش روزانه، پرفروش‌ترین محصولات و برترین معرف‌ها (/analytics)

آنچه اضافه شد — فاز ۴ (امکانات حرفه‌ای)
------------------------------------------
- REST API: /api/v1/bots ، /api/v1/users ، /api/v1/orders ، /api/v1/products (GET) و
  /api/v1/send-message (POST) — احراز هویت با هدر X-API-Key
- Webhook API: از /notification-settings یک قانون با کانال «Webhook» بسازید تا رویدادها
  به‌صورت POST با بدنه {event, data} به URL دلخواه شما ارسال شوند
- API Key و Permission: ساخت/ابطال کلید API با سطح دسترسی read/write و Rate Limit (/api-keys)
- Telegram Mini App: ساخت صفحه HTML/CSS/JS اختصاصی، انتشار در آدرس عمومی
  /app/{bot_id}/{slug} و اتصال آن به دکمه نوع WebApp در Button Builder (/miniapp)
- Template System: ساخت قالب پیام آماده و استفاده سریع از آن هنگام ساخت Broadcast (/templates)
- AI Chatbot: با فعال‌سازی از /ai-settings، ربات به پیام‌هایی که هیچ Command/Automation ای
  آن‌ها را نمی‌گیرد با هوش مصنوعی و بر اساس دانش پایه شما پاسخ می‌دهد
- AI Support: در صفحه هر تیکت دکمه «پیشنهاد پاسخ با AI» یک پیش‌نویس پاسخ بر اساس گفتگو و
  دانش پایه (/ai-knowledge) پیشنهاد می‌دهد که ادمین می‌تواند ویرایش و ارسال کند
- AI Content Generator: تولید کپشن تبلیغاتی/توضیح محصول/پیش‌نویس پاسخ با یک کلیک (/ai/generate)

نکات مهم درباره AI
-------------------
- در /ai-settings باید یک API Key از یک سرویس سازگار با فرمت OpenAI Chat Completions وارد کنید
  (مثل خود OpenAI یا هر سرویس/پروکسی سازگار دیگر با تنظیم فیلد «API Base»).
- بدون تنظیم و فعال‌سازی این بخش، AI Chatbot / AI Support / AI Content Generator غیرفعال
  می‌مانند و بقیه سیستم (فاز ۱ تا ۴ دیگر) کاملاً مستقل از آن کار می‌کند.

وبهوک کردن ربات (Webhook)
===========================
این پروژه Webhook را کاملاً خودکار مدیریت می‌کند؛ نیازی به تنظیم دستی در جای دیگر نیست:

۱. وارد پنل کاربری شوید → منوی «ربات‌ها» (/bots) → با توکن دریافتی از @BotFather ربات را بسازید.
۲. روی همان ربات دکمه «تنظیم Webhook» را بزنید. این کار درخواست POST به مسیر /bots/webhook
   می‌فرستد که به‌صورت خودکار:
   - آدرس Webhook را می‌سازد: https://دامنه‌شما/telegram/webhook/{bot_id}
   - یک secret_token تصادفی و امن تولید و در دیتابیس ذخیره می‌کند
   - متد setWebhook تلگرام را با همان آدرس و secret_token صدا می‌زند
۳. برای بررسی وضعیت، از دکمه/مسیر «اطلاعات Webhook» (/webhook/info?id=BOT_ID) استفاده کنید؛
   این دقیقاً خروجی getWebhookInfo تلگرام (آخرین خطا، تعداد آپدیت در صف و ...) را نشان می‌دهد.
۴. برای قطع موقت، دکمه «حذف Webhook» (/bots/webhook/delete) را بزنید؛ برای اتصال دوباره کافی است
   دکمه «تنظیم Webhook» را دوباره بزنید.

نکات مهم برای اینکه Webhook درست کار کند
------------------------------------------
- دامنه باید HTTPS معتبر (نه Self-Signed) داشته باشد؛ تلگرام آدرس HTTP را قبول نمی‌کند.
- با مسیر /telegram/webhook/{bot_id} مستقیماً کاری نداشته باشید — این مسیر عمومی است چون
  خودِ سرورهای تلگرام آن را صدا می‌زنند (بدون لاگین پنل)؛ امنیتش با بررسی هدر
  X-Telegram-Bot-Api-Secret-Token در public/index.php تامین می‌شود، نه با لاگین.
- اگر بعد از تنظیم، ربات پاسخ نمی‌دهد:
  • مطمئن شوید وضعیت ربات در /bots روی «فعال» است.
  • از /webhook/info بررسی کنید فیلد last_error_message خالی باشد.
  • لاگ‌های PHP سرور (error_log) را چک کنید — اگر بروت‌فورس یا Rate Limit میزبان فعال است،
    درخواست‌های تلگرام ممکن است بلاک شوند.
  • برای Broadcast، Automation تاخیری و انقضای خودکار اشتراک، حتماً Cron روی cron/worker.php
    هر ۱ دقیقه اجرا شود (بخش ۴ نصب را ببینید) — این‌ها جدا از Webhook هستند.
- هر ربات وبهوک و secret_token مستقل خودش را دارد؛ حذف/تغییر توکن یک ربات روی بقیه اثر ندارد.

محدودیت‌های آگاهانه این تحویل
--------------------------------
- Form Builder فعلاً از سمت پنل کامل CRUD دارد؛ برای پر شدن خودکار فرم داخل مکالمه تلگرام
  (چند مرحله‌ای، Step by step) باید Node اختصاصی «Form» در Workflow Builder توسعه داده شود که
  در این تحویل نیست (ساختار دیتابیسی و پنل مدیریت پاسخ‌ها آماده است).
- Department روی Ticket فقط ستون دیتابیسی دارد؛ UI انتخاب Department در فرم پاسخ اضافه نشده.
- AI Provider فقط از فرمت OpenAI-Compatible پشتیبانی می‌کند (اکثر سرویس‌های فارسی/خارجی این
  فرمت را دارند یا پروکسی سازگار با آن ارائه می‌دهند).
