SeoPulse PHP — گزارش فقط‌خواندنی Google Search Console
======================================================

این نسخه ترافیک تولید نمی‌کند، بازدید نمی‌سازد، نتیجه جستجو را شبیه‌سازی نمی‌کند و
Referer گوگل جعل نمی‌کند. داشبورد فقط کلیک‌ها و نمایش‌های ثبت‌شده برای property
تأییدشده را از Search Console می‌خواند. گزارش‌ها تجمیعی‌اند، اطلاعات هویتی کاربران
را نشان نمی‌دهند و ممکن است چند روز تأخیر داشته باشند.

۱) پیش‌نیازها
-------------
- PHP نسخه 8.0 یا جدیدتر
- افزونه‌های PHP cURL، OpenSSL و JSON
- وب‌سرور با HTTPS
- یک تا ۵۰ property تأییدشده در Google Search Console
- یک Google Cloud Service Account مشترک با دسترسی خواندن به همه propertyها

۲) نصب آسان با نصب‌کننده وب
---------------------------
1. پوشه php-edition را روی هاست PHP خود بارگذاری کنید. چون کلید/رمز جداگانهٔ نصب‌کننده
   وجود ندارد، صفحه را فقط هنگام راه‌اندازی و با HTTPS باز کنید؛ در صورت امکان دسترسی را
   موقتاً به IP خود محدود کنید و نصب را بی‌درنگ انجام دهید. اولین پیکربندی موفق قفل می‌شود.
2. در صورت آماده‌بودن، Search Console API را در Google Cloud فعال کنید، یک Service Account
   بسازید و ایمیل آن را با دسترسی خواندن به propertyهای موردنظر اضافه کنید. یک حساب سرویس
   مشترک برای همه سایت‌ها کافی است؛ می‌توانید فایل JSON را در همین نصب بارگذاری کنید یا
   اتصال Google را بعداً از تنظیمات سرور انجام دهید.
3. install.php را از HTTPS باز کنید و یک نام کاربری و رمز مدیر (حداقل ۱۶ نویسه) بسازید.
   همین یک جفت، اطلاعات ورود داشبورد است؛ رمز اضافه‌ای برای نصب‌کننده وجود ندارد.
4. پس از موفقیت، نصب‌کننده خودکار به install.locked.php تغییرنام می‌یابد و تنظیم اولیه
   دیگر قابل اجرا نیست. فایل تغییرنام‌یافته را از هاست حذف کنید. اگر مجوز هاست اجازه
   تغییرنام نداد، install.php را دستی حذف یا تغییرنام دهید؛ پیکربندی موجود از نصب مجدد
   جلوگیری می‌کند.
5. وارد index.php شوید و از بخش «افزودن سایت» propertyهای تأییدشده را داخل داشبورد اضافه
   کنید. می‌توان تا ۵۰ سایت افزود؛ همان Service Account باید به همه دسترسی فقط‌خواندنی داشته باشد.

اگر فایل JSON را در نصب‌کننده بارگذاری کنید، خارج از web root ذخیره می‌شود. اگر هاست
اجازه ساخت مسیر خصوصی را ندهد، فایل را در پوشه‌ای خصوصی بیرون از web root بگذارید و از
روش تنظیم دستی پایین استفاده کنید.

۳) اتصال و پیکربندی دستی (جایگزین نصب‌کننده)
--------------------------------------------
1. از ایمیل Service Account مطمئن شوید که به تک‌تک propertyهای موردنظر دسترسی خواندن دارد.
2. فایل JSON کلید را بیرون از web root و مخزن سورس نگه دارید؛ مثلاً:

      /home/USERNAME/private/gsc-service-account.json

3. فایل php-edition/storage/app_config.php را روی هاست بسازید و مقادیر واقعی را وارد
   کنید. برای تولید hash روی سیستمی که PHP CLI دارد:

      php -r 'echo password_hash("یک-رمز-طولانی-و-یکتا", PASSWORD_DEFAULT), PHP_EOL;'

   نمونه:

      <?php
      return [
          'admin_username' => 'admin',
          'admin_password_hash' => '$2y$10$...خروجی-واقعی-password_hash...',
          'gsc_service_account_file' => '/home/USERNAME/private/gsc-service-account.json',
      ];

   برای هر URL-prefix نشانی دقیق مثل https://example.com/ را بگذارید.
   متغیرهای محیطی SEOPULSE_ADMIN_USERNAME، SEOPULSE_ADMIN_PASSWORD_HASH،
   GSC_PROPERTIES و GSC_SERVICE_ACCOUNT_FILE پشتیبانی می‌شوند. فهرست‌های محیطی یا
   app_config.php برای سازگاری با نصب‌های قدیمی باقی مانده‌اند؛ پس از ورود، سایت‌های
   جدید را از داخل داشبورد اضافه کنید. آن‌ها در storage/gsc-properties.json با مجوز محدود
   نگهداری می‌شوند و .htaccess دسترسی وب به storage را مسدود می‌کند. برای نصب قدیمی
   تک‌سایته، GSC_PROPERTY نیز پشتیبانی می‌شود. رمز خام SEOPULSE_ADMIN_PASSWORD فقط
   به‌عنوان جایگزین پذیرفته می‌شود و hash ترجیح دارد.

4. PHP باید فایل کلید را بخواند، اما آن نباید از وب قابل دریافت باشد. در Apache فایل
   storage/.htaccess دسترسی را می‌بندد؛ در Nginx برای /storage قانون deny جداگانه
   بنویسید. بهتر است کلید حتماً بیرون از web root باشد.

۴) تنظیم reverse proxy
----------------------
به‌طور پیش‌فرض، کوکی Secure و محدودکننده تلاش ورود از نشانی واقعی اتصال PHP استفاده
می‌کنند. اگر HTTPS پشت reverse proxy خاتمه می‌یابد و proxy شما هدرها را پاک‌سازی و
خودش بازنویسی می‌کند، فقط در همان شرایط SEOPULSE_TRUST_PROXY_HEADERS=1 را تنظیم کنید.
در غیر این صورت این متغیر را نگذارید؛ هرگز به X-Forwarded-For ارسالی مستقیم کاربر اعتماد
نکنید. اگر همه کاربران پشت یک proxy هستند، محدودسازی اضافه را روی خود proxy/WAF فعال کنید.

۵) رفتار نسخه فعلی و نسخه‌های قبلی
-----------------------------------
- داشبورد فقط Search Analytics API را با scope مجوز webmasters.readonly می‌خواند.
- install.php پس از نصب خودکار به install.locked.php تغییرنام می‌یابد؛ فایل قفل‌شده را از هاست پاک کنید.
- APIهای قدیمی تولید کمپین، dispatch، worker و خروجی لاگ با HTTP 410 غیرفعال‌اند.
- cron.php قدیمی دیگر worker اجرا نمی‌کند. هر Cron Job مرتبط را از پنل هاست حذف کنید.
- daemon قدیمی ترافیک مصنوعی را در پنل هاست متوقف کنید.
- دیتابیس‌ها و جدول‌های نسخه قدیمی برای گزارش Search Console لازم نیستند؛ پیش از حذف
  داده‌های قبلی، از آن‌ها نسخه پشتیبان بگیرید.

اگر خطای دسترسی Google گرفتید، فعال‌بودن Search Console API، property دقیق، مجوز خواندن
Service Account، ساعت سرور و گواهی TLS هاست را بررسی کنید. Domain property و URL-prefix
دو property جداگانه‌اند.