# گسترده — پلتفرم تبلیغات تلگرام

پلتفرمی کامل روی Telegram برای **تبلیغات و کمپین**، **کیف پول و Ledger مالی**، **پرداخت ریالی و رمزارزی**، **برداشت**، **زیرمجموعه‌گیری**، **پشتیبانی** و **پنل مدیریت با نقش و دسترسی**.

- PHP ≥ 8.2 · MySQL 8 / MariaDB ≥ 10.5 · Redis · Nginx · Supervisor
- بدون وابستگی اجباری Composer (کلاینت Redis، HTTP، Queue، Migration و DI داخلی هستند)
- Multi-Bot، چندزبانه‌پذیر، Queue/Worker محور

## مدل کسب‌وکار در یک نگاه

```text
تبلیغ‌دهنده ── سفارش (ظرفیت × قیمت واحد) ──► پرداخت از کیف پول ──► کمپین (تأیید مدیر) ──► فعال
ناشر ── دریافت لینک اختصاصی ──► انتشار ──► عضو از لینک وارد می‌شود (chat_member)
        └─► درآمد Pending ──(پایان دوره‌ی نگهداری)──► قابل برداشت + کمیسیون زیرمجموعه
            └─ خروج زودهنگام عضو ──► برگشت درآمد و آزاد شدن ظرفیت
ظرفیت پر شد ──► کمپین completed (دقیقاً یک‌بار) ──► بودجه‌ی مصرف‌نشده به تبلیغ‌دهنده برمی‌گردد
```

## شروع سریع (محیط توسعه)

```bash
cp .env.example .env
php bin/console key:generate
# برای اجرای محلی بدون MySQL/Redis:  DB_DRIVER=sqlite  و  REDIS_DRIVER=array  در .env
php bin/console migrate --seed
php bin/console test
```

نصب روی سرور: [docs/installation.md](docs/installation.md)

## ساختار

```text
app/
├── Core/         Container, Config, Database (+Schema/Migrator), Redis, Queue, Cache, Lock,
│                 RateLimiter, Logger, Http, Events, I18n, Settings, Console
├── Controllers/  Webhook, PaymentCallback, Health, AdminApi
├── Console/      فرمان‌های bin/console
├── Jobs/         کارهای صف و کارهای دوره‌ای
├── Workers/      HealthService
├── Telegram/     BotApi, Dispatcher, Context, State, Flows/, Handlers/ (+Admin/)
├── Bots/ Users/ Wallet/ Channels/ Campaigns/ Orders/ Payments/ Withdrawals/
├── Referrals/ Kyc/ Support/ Notifications/ Broadcast/ Ranking/ Reports/
├── Admin/        Authorizer (RBAC), AuditLogger, سرویس‌های مدیریتی، Search, Export
└── Security/     Encryption, FraudDetector, AbuseGuard, CryptoAddress
config/           تنظیمات محیطی (از .env) + تعریف Settings، درگاه‌ها، انواع تبلیغ، رویدادها
database/         migrations/ و seeders/
resources/        messages/fa.php (همه‌ی متن‌ها) و keyboards/
routes/           web.php · telegram.php · console.php · schedule.php
deploy/           nginx · php-fpm · supervisor · cron
scripts/          install.sh · deploy.sh
tests/            Unit/ و Feature/ (+ Runner داخلی)
docs/             مستندات
```

## فرمان‌ها

| فرمان | کار |
|---|---|
| `php bin/console key:generate` | ساخت `APP_KEY` |
| `php bin/console migrate [--seed\|--status\|--rollback]` | Migration |
| `php bin/console db:seed` | دسترسی‌ها، نقش‌ها، تعرفه‌ها (Idempotent) |
| `php bin/console bot:add [key]` | ثبت ربات (توکن از `.env` خوانده و رمزشده ذخیره می‌شود) |
| `php bin/console webhook:set [key] [--info]` | تنظیم / نمایش Webhook |
| `php bin/console admin:create <telegram_id> [--role=…\|--super]` | ساخت مدیر |
| `php bin/console queue:work <queues> [--once]` | اجرای Worker |
| `php bin/console queue:failed [--retry=ID\|all] [--flush]` | Jobهای ناموفق |
| `php bin/console schedule:run` | Scheduler (هر دقیقه از Cron) |
| `php bin/console health:check [--json]` | سلامت سرویس‌ها |
| `php bin/console backup:run` / `backup:restore <file> --force` | پشتیبان / بازیابی |
| `php bin/console test [filter]` | اجرای تست‌ها |

## تضمین‌های کلیدی

| تضمین | سازوکار |
|---|---|
| هیچ تغییر موجودی بدون Ledger | فقط `WalletService` جدول `wallets` را تغییر می‌دهد؛ هر تغییر یک ردیف `wallet_transactions` با موجودی قبل و بعد |
| عدم خطای هم‌زمانی | `SELECT … FOR UPDATE` روی کیف پول، قفل مرتب برای چند کیف پول، `CHECK (available >= 0)` در دیتابیس |
| Idempotency | کلید یکتا در DB برای پرداخت، برداشت، سفارش، Ledger؛ تغییر وضعیت با `UPDATE … WHERE status = ?` |
| پرداخت فقط پس از Verify | Callback هیچ‌وقت به‌تنهایی کافی نیست؛ همیشه از درگاه/زنجیره استعلام می‌شود |
| مجوز Server-Side | همه‌ی عملیات مدیریتی از `App\Admin\*Service` می‌گذرند: `authorize()` + `AuditLogger` |
| عدم نمایش خطا به کاربر | پیام خنثی + کد پیگیری؛ جزئیات فقط در لاگ (با حذف Secretها) |
| عدم از دست رفتن کار | صف با Reserve/Ack، Retry با Backoff، `failed_jobs`، بازیابی کار Worker کرش‌کرده |

## مستندات

| سند | موضوع |
|---|---|
| [docs/design/](docs/design/) | معماری، ERD، Flowها، Feature Map |
| [docs/installation.md](docs/installation.md) | PHP، MySQL، Redis، Nginx، SSL، Supervisor، Cron، Webhook |
| [docs/configuration.md](docs/configuration.md) | `.env`، Settings، Feature Flag، متن‌ها و Keyboardها، Multi-Bot |
| [docs/database.md](docs/database.md) | جداول، قیود، Migration |
| [docs/telegram.md](docs/telegram.md) | مسیر Update، Flowها، افزودن Handler / زبان |
| [docs/payments.md](docs/payments.md) | درگاه‌ها، Flow هر کدام، افزودن درگاه و روش برداشت |
| [docs/workers.md](docs/workers.md) | صف‌ها، Workerها، Supervisor، Cron، Health |
| [docs/backup-restore.md](docs/backup-restore.md) | پشتیبان‌گیری، Rotation، بازیابی |
| [docs/api.md](docs/api.md) | Endpointهای HTTP و Admin API |
| [docs/security.md](docs/security.md) | مدل تهدید و کنترل‌ها |
| [docs/admin-guide.md](docs/admin-guide.md) | راهنمای پنل مدیریت |
| [docs/troubleshooting.md](docs/troubleshooting.md) | عیب‌یابی |

## وضعیت تست

`php bin/console test` — ۸۶ تست (هسته، ثبت‌نام، کیف پول، انتقال، پرداخت، برداشت، سفارش، کمپین، Join Tracking، Referral، مجوزها، شبیه‌سازی کامل ربات و پنل مدیریت، و مسابقه‌ی چند پردازه برای سناریوهای مالی).

تست‌ها به‌صورت پیش‌فرض روی SQLite و Redis درون‌پردازه‌ای اجرا می‌شوند تا بدون هیچ سرویس خارجی قابل اجرا باشند. قبل از Production همین مجموعه را با `TEST_DB_DRIVER=mysql` روی سرور Staging اجرا کنید (بخش «تست روی MySQL» در [docs/installation.md](docs/installation.md)).