═══════════════════════════════════════════════════════════════
  خبرخوان روی هاست اشتراکی  —  راهنمای نصب
  دامنه نمونه: https://dl.vr360iran.ir/relay/
═══════════════════════════════════════════════════════════════

این بسته فقط «نمایشگر + پل» است.
موتور واقعی (Playwright، اسکرین‌شات، کاور، زمان‌بند) همان برنامه
ویندوزی است و باید روی کامپیوتر روشن بماند.


───────────────── ۱) روی هاست ─────────────────

1. همه‌ی محتویات این پوشه را در مسیر عمومی هاست آپلود کن، مثلاً:
      public_html/relay/
   تا آدرس نهایی بشود:
      https://dl.vr360iran.ir/relay/

2. فایل config.php را باز کن و AGENT_KEY را عوض کن:
      const AGENT_KEY = 'یک-رمز-بلند-تصادفی-حداقل-۳۲-کاراکتر';

3. مطمئن شو پوشه‌ی _relay_data قابل‌نوشتن است
   (معمولاً 755 یا 775؛ اگر نشد 775 روی _relay_data).

4. اگر .htaccess کار نکرد (بعضی هاست‌ها rewrite را محدود می‌کنند):
   - در پنل هاست «Rewrite» را فعال کن، یا
   - موقتاً مستقیم با index.php تست کن.

5. تست سریع (بدون نیاز به ویندوز):
      https://dl.vr360iran.ir/relay/__ping
   باید JSON با ok:true برگرداند.


───────────────── ۲) روی ویندوز ─────────────────

1. کنار بقیه‌ی فایل‌های پروژه، فایل data/relay.json بساز:

{
  "relay_url": "https://dl.vr360iran.ir/relay",
  "agent_key": "همان-رمز-داخل-config.php",
  "local_url": "http://127.0.0.1:8787"
}

   توجه: بدون اسلش آخر. اگر اپ در ریشه‌ی دامنه است همان ریشه را بگذار.

2. دو برنامه را با هم اجرا کن (دو پنجره یا دو سرویس):

      python main_web.py --local-only
      python relay_agent.py

   --local-only یعنی سرور فقط روی localhost گوش می‌دهد؛
   دسترسی از بیرون فقط از طریق هاست انجام می‌شود (امن‌تر).

3. در خروجی relay_agent باید ببینی:
      ✅ عامل پل روشن شد → https://dl.vr360iran.ir/relay


───────────────── ۳) روی گوشی ─────────────────

1. در Chrome یا مرورگر گوشی باز کن:
      https://dl.vr360iran.ir/relay/?token=محتویات-فایل-data/web_token.txt

2. بعد از ورود موفق، از منوی مرورگر «Add to Home screen» را بزن
   تا مثل اپ روی صفحه‌ی اصلی بنشیند.

3. همه‌ی امکانات قبلی کار می‌کند:
   اخبار، سایت‌ها، کلمات، دسته‌ها، تصاویر، تنظیمات، لاگ،
   ساخت کاور، اشتراک‌گذاری (چون سایت HTTPS است)، اجرای دستی، زمان‌بند.


───────────────── نکات مهم ─────────────────

• کامپیوتر باید روشن بماند و Sleep ویندوز خاموش باشد.
• اگر عامل قطع شود، سایت صفحه‌ی راهنما (504) نشان می‌دهد.
• ساخت کاور گاهی ۲۰–۶۰ ثانیه طول می‌کشد؛ WAIT_MAX در config.php
  را در صورت نیاز بالا ببر (مثلاً ۱۲۰).
• پورت مودم را باز نکن. هاست فقط با عامل صحبت می‌کند.
• اگر AGENT_KEY لو رفت، هم در config.php و هم در relay.json عوض کن.


───────────────── ساختار فایل‌های هاست ─────────────────

relay/
  index.php          ← ورودی اصلی (UI + پل)
  config.php         ← رمز و تنظیمات
  app.html           ← همان رابط لمسی خبرخوان
  manifest.webmanifest
  .htaccess
  _relay_data/       ← صف jobها (خودکار ساخته می‌شود)
    .htaccess
    jobs/
    results/
  README-HOST.txt
