# راهنمای نصب و راه‌اندازی TeleCard Bot

---

## ساختار پوشه‌ها

```
telecard/
├── bootstrap.php           # بارگذاری اولیه
├── setup_webhook.php       # اجرای یک‌بار برای ثبت وب‌هوک
├── .env.example            # نمونه فایل تنظیمات
├── .env                    # فایل تنظیمات (خودتان بسازید)
├── .htaccess               # محافظت ریشه
│
├── config/
│   └── config.php          # ثابت‌ها و تنظیمات بازی
│
├── src/
│   ├── Controllers/
│   │   ├── MessageController.php
│   │   └── CallbackController.php
│   ├── Models/
│   │   ├── UserModel.php
│   │   ├── CardModel.php
│   │   └── DeckModel.php
│   ├── Services/
│   │   ├── BattleEngine.php
│   │   ├── BattleService.php
│   │   ├── SpawnService.php
│   │   ├── ShopService.php
│   │   └── TradeService.php
│   └── Helpers/
│       ├── Database.php
│       ├── Telegram.php
│       ├── Logger.php
│       └── RateLimiter.php
│
├── public/
│   ├── index.php           # نقطه ورود وب‌هوک
│   └── .htaccess
│
├── database/
│   └── install.sql         # اسکریپت نصب دیتابیس
│
└── logs/                   # لاگ‌ها (خودکار ساخته می‌شود)
```

---

## مرحله ۱: ساخت ربات

1. در تلگرام به `@BotFather` پیام بدید
2. `/newbot` بزنید و نام و یوزرنیم انتخاب کنید
3. توکن را ذخیره کنید

---

## مرحله ۲: آپلود فایل‌ها روی هاست

1. وارد **cPanel** هاست شوید
2. در **File Manager** بروید به `public_html` یا یک زیرپوشه دلخواه
3. فولدر `telecard` را آپلود کنید (یا ZipArchive را extract کنید)
4. مطمئن شوید ساختار فایل‌ها درست است

---

## مرحله ۳: ساخت دیتابیس

1. در cPanel → **MySQL Databases** بروید
2. یک دیتابیس جدید بسازید: مثلاً `user_telecard`
3. یک کاربر MySQL بسازید و به دیتابیس دسترسی کامل بدید
4. در **phpMyAdmin** دیتابیس را انتخاب کنید
5. تب **Import** را بزنید و فایل `database/install.sql` را آپلود و اجرا کنید

---

## مرحله ۴: تنظیم فایل .env

1. فایل `.env.example` را کپی کنید و نام آن را به `.env` تغییر دهید
2. مقادیر زیر را پر کنید:

```env
BOT_TOKEN=1234567890:AAExxxxxxxxxxxxxxxxxxxxxx
WEBHOOK_SECRET=یک_رشته_رندوم_قوی_بسازید
DB_HOST=localhost
DB_NAME=username_telecard
DB_USER=username_dbuser
DB_PASS=password
BASE_URL=https://yourdomain.com/telecard
```

**توجه:** برای `WEBHOOK_SECRET` یک رشته رندوم قوی مثل `a3f9b2e1c7d4` بسازید.

---

## مرحله ۵: ثبت وب‌هوک

### روش اول: از طریق SSH یا cPanel Terminal
```bash
cd /home/username/public_html/telecard
php setup_webhook.php
```

### روش دوم: از طریق مرورگر
آدرس زیر را باز کنید:
```
https://yourdomain.com/telecard/setup_webhook.php
```
(بعد از موفقیت، این فایل را پاک کنید!)

### روش سوم: درخواست مستقیم به API تلگرام
```
https://api.telegram.org/bot[TOKEN]/setWebhook?url=https://yourdomain.com/telecard/public/index.php&secret_token=[SECRET]
```

---

## مرحله ۶: اضافه کردن ربات به گروه

1. ربات را به گروه اضافه کنید
2. ربات را **ادمین** کنید (دسترسی ارسال پیام لازم است)
3. اعضا شروع به پیام دادن می‌کنند → هر ۱۰۰ پیام یک کارت اسپاون می‌شود

---

## بررسی صحت نصب

آدرس زیر باید `403 Forbidden` برگرداند (چون GET درخواست می‌دهیم):
```
https://yourdomain.com/telecard/public/index.php
```

---

## تنظیمات امنیتی اضافه (توصیه می‌شود)

### ۱. مخفی کردن فایل .env
در `.htaccess` ریشه این خط وجود دارد:
```apache
<FilesMatch "\.env">
    Deny from all
</FilesMatch>
```

### ۲. محدود کردن دسترسی به setup_webhook.php
بعد از ثبت وب‌هوک، این فایل را **حذف** کنید.

### ۳. SSL اجباری
برای وب‌هوک تلگرام، SSL (https) الزامی است. مطمئن شوید هاست شما SSL دارد.

---

## بررسی لاگ‌ها

لاگ‌های خطا در فایل `logs/app.log` ذخیره می‌شوند.

---

## فرمول آمارهای کارت

### سیستم سطح‌بندی
- هر سطح بالاتر: **+۳٪** به تمام آمارها
- فرمول هزینه ارتقا: `50 × level^1.5`
  - سطح ۱→۲: ~۵۰ سکه
  - سطح ۵→۶: ~۲۸۰ سکه  
  - سطح ۱۰→۱۱: ~۱۵۸۰ سکه

### فرمول آسیب
```
Damage = (ATK × random(0.9 - 1.1)) - (DEF × 0.4)
```
- ضریب کریت: ۱.۷×
- حداقل آسیب: ۱

### سطح‌بندی کاربر از XP
```
Level = floor(sqrt(XP / 100)) + 1
```

---

## دستورات بات (فارسی)

| دستور | توضیح |
|-------|-------|
| /start | شروع و راهنما |
| /profile یا /me | پروفایل و آمار |
| /cards | مشاهده کارت‌ها |
| /deck | مشاهده دک |
| /setdeck [slot] [id] | تنظیم دک |
| /fight @user [bet] | چالش نبرد |
| /shop | فروشگاه |
| /trades | بازار معاملات |
| /trade sell [id] [price] | فروش کارت |
| /buy [trade_id] | خرید کارت |
| /levelup [card_id] | ارتقا سطح کارت |
| /merge [id1] [id2] | ادغام کارت‌ها |
| /top | جدول برترین‌ها |
| /help | راهنما |
| Catch | گرفتن کارت اسپاون شده |