# پیکربندی

سه لایه وجود دارد:

| لایه | کجا | چه چیزی | چه کسی تغییر می‌دهد |
|---|---|---|---|
| محیط | `.env` → `config/*.php` | اتصال‌ها و Secretها | مدیر سرور (نیاز به ری‌استارت Workerها) |
| تنظیمات زمان اجرا | جدول `settings` (تعریف‌ها در `config/settings.php`) | کارمزدها، سقف‌ها، Feature Flagها، متن‌ها | مدیر از داخل ربات (بدون ری‌استارت، حداکثر ۵ ثانیه تأخیر) |
| کد | `config/payments.php`, `config/campaigns.php`, `config/events.php`, `routes/*` | ثبت درگاه، نوع تبلیغ، Listener، مسیر | توسعه‌دهنده |

## `.env`

هیچ Secret واقعی در Git قرار نمی‌گیرد؛ `.env` در `.gitignore` است و باید `chmod 600` باشد. متغیرهای واقعی محیط (systemd، Docker، Secret Manager) بر فایل `.env` مقدم‌اند.

| متغیر | توضیح |
|---|---|
| `APP_ENV`, `APP_DEBUG` | `production` / `false` روی سرور. `APP_DEBUG=true` فقط لاگ `debug` را روشن می‌کند؛ خطا هیچ‌وقت به کاربر نمایش داده نمی‌شود. |
| `APP_URL` | آدرس HTTPS عمومی؛ برای Webhook و Callback پرداخت |
| `APP_KEY` | کلید ۳۲ بایتی (base64) برای AES-256-GCM. با `key:generate` ساخته می‌شود. **تغییر آن داده‌های رمزشده را غیرقابل‌خواندن می‌کند.** |
| `SUPER_ADMIN_IDS` | شناسه‌های تلگرام با دسترسی کامل (با ویرگول) |
| `DB_*` | اتصال MySQL/MariaDB. `DB_DRIVER=sqlite` فقط برای تست/توسعه |
| `REDIS_*` | اتصال Redis. `REDIS_DRIVER=array` فقط تست/توسعه (صف هم‌زمان اجرا می‌شود) |
| `TELEGRAM_BOT_*` | مشخصات ربات پیش‌فرض برای `bot:add` |
| `TELEGRAM_ADMIN_CHAT_ID` | چتی که هشدارهای مدیریتی به آن می‌رود (برداشت جدید، تیکت، ریسک، سلامت) |
| `TELEGRAM_RATE_PER_SECOND` | سقف ارسال پیام خودکار در ثانیه به ازای هر ربات (پیش‌فرض ۲۵) |
| `QUEUE_*` | مهلت Reserve، تعداد Job و سقف حافظه‌ی هر Worker قبل از ری‌استارت |
| `ZARINPAL_*`, `NOWPAYMENTS_*`, `PAYMENT4_*` | کلیدهای درگاه‌ها |
| `TRON_*`, `TON_*` | آدرس خزانه، کلید API و حداقل تأیید شبکه |
| `RATE_PROVIDER` | `nobitex` (نرخ لحظه‌ای + Fallback به تنظیمات) یا `settings` (نرخ دستی) |
| `HEALTH_TOKEN` | توکن مشاهده‌ی جزئیات `/health` |
| `ADMIN_API_ENABLED`, `ADMIN_API_ALLOWED_IPS` | فعال‌سازی و محدودسازی IP برای Admin API |
| `BACKUP_*` | مسیر، مدت نگهداری و مسیر `mysqldump` / `mysql` |

## تنظیمات زمان اجرا

پنل مدیریت ← ⚙️ تنظیمات. همه‌ی کلیدها، نوع و مقدار پیش‌فرضشان در `config/settings.php` تعریف شده‌اند.

| گروه | کلیدهای مهم |
|---|---|
| قابلیت‌ها | `feature.campaigns`, `feature.referral`, `feature.withdrawal`, `feature.transfer`, `feature.crypto`, `feature.tron`, `feature.ton`, `feature.zarinpal`, `feature.payment4`, `feature.nowpayments`, `feature.authentication`, `feature.broadcast`, `feature.force_join`, `feature.support` |
| سیستم | `maintenance.enabled`, `force_join.channels`, `broadcast.batch_size` |
| کمیسیون | `referral.levels` (مثلاً `5 2` = سطح ۱: ۵٪، سطح ۲: ۲٪)، `referral.signup_bonus`, `commission.campaign_percent`, `commission.sales_percent`, `commission.partner_percent` |
| کمپین | `campaign.auto_approve`, `campaign.hold_hours`, `campaign.min_capacity`, `campaign.max_capacity`, `campaign.default_days`, `campaign.max_active_per_user`, `campaign.max_links_per_publisher` |
| سفارش/شارژ | `order.min_amount`, `order.unpaid_ttl_minutes`, `deposit.min`, `deposit.max`, `payment.ttl_minutes`, `wallet.deposits_withdrawable` |
| برداشت | `withdrawal.min`, `withdrawal.max`, `withdrawal.fee_percent`, `withdrawal.fee_fixed`, `withdrawal.daily_count`, `withdrawal.require_kyc`, `withdrawal.pending_ttl_days` |
| انتقال | `transfer.min`, `transfer.max`, `transfer.daily_limit`, `transfer.fee_percent` |
| نرخ | `rate.trx`, `rate.ton`, `rate.usdt` (تومان به ازای هر واحد) |
| رتبه‌بندی | `ranking.weight_purchase`, `…_income`, `…_orders`, `…_referrals`, `…_activity` |
| امنیت | `fraud.fast_leave_seconds`, `fraud.join_burst_count`, `fraud.join_burst_window`, `fraud.repeat_leave_count`, `fraud.suspend_link_score`, `kyc.ttl_days` |

ترتیب خواندن: تنظیم اختصاصی ربات (`bot_id`) ← تنظیم سراسری (`bot_id = 0`) ← پیش‌فرض `config/settings.php`.

### افزودن یک تنظیم جدید

یک خط در `config/settings.php` اضافه کنید و در کد `Settings::get('my.key')` بخوانید. تنظیم به‌صورت خودکار در پنل، در گروه خودش، قابل ویرایش می‌شود.

## متن‌ها و Keyboardها

- همه‌ی متن‌ها در `resources/messages/fa.php` هستند (کلید ← متن با جای‌نگهدار `{name}`، قالب Telegram HTML).
- **آیکون‌ها**: در متن‌ها با `{i:name}` به یک آیکون از `resources/icons.php` اشاره می‌شود (شناسه‌ی ایموجی سفارشی تلگرام + ایموجی معمولی جایگزین). برای عوض کردن ظاهر کل ربات فقط همین فایل را ویرایش کنید.
- **رنگ و آیکون دکمه‌ها** در خودِ متن دکمه است: `'btn.new_order' => '!primary {i:order} سفارش تبلیغ'` — رنگ‌ها `!primary` (آبی)، `!success` (سبز)، `!danger` (قرمز). این قاعده برای دکمه‌های منو و دکمه‌های شیشه‌ای یکسان است.
- ایموجی سفارشی (روی دکمه و در متن) فقط وقتی نمایش داده می‌شود که مالک ربات Telegram Premium داشته باشد. اگر ندارد یا دکمه‌ها خطا می‌دهند، تنظیم **«آیکون‌های پرمیوم»** (سیستم ← `ui.premium_emoji`) را خاموش کنید؛ ربات با ایموجی معمولی کار می‌کند و دکمه‌های قبلیِ کاربران هم همچنان شناخته می‌شوند.
- **بدون تغییر کد**: پنل ← تنظیمات ← «📝 ویرایش متن‌های ربات» ← کلید ← متن جدید. بازنویسی‌ها در `settings` با کلید `text.{locale}.{key}` ذخیره می‌شوند؛ ارسال `-` متن پیش‌فرض را برمی‌گرداند.
- چیدمان منوها: `resources/keyboards/` — `main` (منوی اصلی)، `finance` (امور مالی)، `account` (حساب کاربری)، `admin` (پنل مدیریت)، `flow` و `confirm` (حین فرآیندها). هر فایل ردیف‌هایی از کلید متن است. بازنویسی زمان اجرا: تنظیم `keyboard.{name}` با همان ساختار JSON. دکمه‌ای که Feature Flag آن خاموش است یا مدیر دسترسی‌اش را ندارد خودکار حذف می‌شود.
- برچسب دکمه‌ها همان کلیدهای `btn.*` هستند؛ با تغییر متن یک دکمه، مسیریابی آن هم خودکار با متن جدید کار می‌کند. فقط دقت کنید دو دکمه‌ی منو متن یکسان نداشته باشند (تست `MessagesTest` این را بررسی می‌کند).

## زبان جدید

`resources/messages/fa.php` را به `en.php` یا `ar.php` کپی و ترجمه کنید. زبان در ⚙️ تنظیماتِ ربات قابل انتخاب می‌شود و در `users.language` می‌ماند. کلیدِ ترجمه‌نشده به زبان پیش‌فرض (`APP_LOCALE`) برمی‌گردد.

## Multi-Bot

```bash
export SECOND_BOT_TOKEN='123:ABC…'
php bin/console bot:add shop --token-env=SECOND_BOT_TOKEN --admin-chat=-100123
php bin/console webhook:set shop          # https://<دامنه>/webhook/shop
```

- هر ربات: توکن (رمزشده)، `webhook_secret`، چت‌های ادمین/پشتیبانی/لاگ و تنظیمات/Feature Flagهای اختصاصی خودش.
- کاربر، کیف پول و Ledger بین ربات‌ها مشترک است؛ `bot_users` عضویت هر کاربر در هر ربات را نگه می‌دارد (برای Broadcast و وضعیت Block).
- کمپین، کانال، سفارش، پرداخت، برداشت و تیکت `bot_id` دارند.
- همان Workerها همه‌ی ربات‌ها را سرویس می‌دهند.