# راهنمای مدیر

پنل مدیریت داخل خود ربات است: دکمه‌ی «پنل مدیریت» در منوی اصلی یا فرمان `/admin`. این دکمه فقط برای مدیران نمایش داده می‌شود و هر بخش فقط در صورت داشتن دسترسی دیده می‌شود. (پنهان بودن دکمه کنترل امنیتی نیست؛ هر عمل در سرور دوباره بررسی می‌شود.)

با ورود به پنل:

- بالای صفحه تعداد موارد **در انتظار رسیدگی** را می‌بینید: برداشت، کمپین، تیکت، احراز هویت، رفتار مشکوک.
- منوی پایین به منوی مدیریت تغییر می‌کند و تا زدن «پنل کاربر» همان می‌ماند.
- ابزارهای کم‌استفاده‌تر (دفتر کل، کانال‌ها، تعرفه‌ها، خروجی داده، لاگ‌ها، سلامت سیستم) پشت دکمه‌ی «سایر ابزارها» هستند.

## دسترسی‌ها

| نقش پیش‌فرض | مناسب برای | دسترسی‌ها |
|---|---|---|
| `super_admin` | مالک | همه چیز |
| `finance` | مالی | کیف پول و اصلاح موجودی، سفارش‌ها، پرداخت‌ها، برداشت‌ها، گزارش‌ها |
| `moderator` | ناظر تبلیغات | کمپین‌ها، کانال‌ها، رفتار مشکوک، مسدودسازی کاربر |
| `support` | پشتیبان | تیکت‌ها، احراز هویت، مشاهده‌ی کاربر و سفارش |
| `analyst` | تحلیلگر | فقط مشاهده، گزارش و خروجی |

- افزودن مدیر: پنل ← 👮 مدیران و نقش‌ها ← ➕ افزودن مدیر ← شناسه یا نام کاربری (فرد باید قبلاً ربات را استارت کرده باشد) ← روی نقش‌ها بزنید تا داده/گرفته شوند.
- تغییر دسترسی‌های یک نقش: 🎭 نقش‌ها ← نقش ← روی هر دسترسی بزنید.
- مدیر تازه بدون نقش هیچ دسترسی‌ای ندارد.
- شناسه‌های `SUPER_ADMIN_IDS` در `.env` همیشه دسترسی کامل دارند (راه نجات در صورت اشتباه در نقش‌ها).

## 📊 داشبورد و گزارش‌ها

- **داشبورد**: کاربران و کاربران فعال، سفارش‌ها، واریزی امروز، پرداخت‌ها و برداشت‌های در انتظار، کمپین‌ها، کانال‌ها، ورود/خروج امروز، مجموع موجودی کاربران، موارد مشکوک، خطاها و وضعیت Workerها.
- **گزارش‌ها**: روزانه / هفتگی / ماهانه — واریزی، سفارش‌ها، حاشیه‌ی پلتفرم، کاربر جدید و فعال، ورود/خروج، کمیسیون زیرمجموعه، برداشت‌ها و عملکرد کمپین‌ها.
- **❤️ سلامت سیستم**: دیتابیس، Redis، صف‌ها، Workerها، Scheduler، درگاه‌ها، تلگرام، دیسک و حافظه. 🔴 یعنی آن سرویس مشکل دارد (جزئیات در [troubleshooting.md](troubleshooting.md)).

## 🔎 جستجو

| ورودی | نتیجه |
|---|---|
| `123456789` یا `@username` | کاربر |
| `o:15` | سفارش ۱۵ |
| `c:7` | کمپین ۷ |
| `p:31` | پرداخت ۳۱ |
| `t:900` | تراکنش Ledger شماره‌ی ۹۰۰ |
| `ch:-1001234567890` یا `ch:@channel` | کانال |
| هش تراکنش / Authority | پرداخت متناظر |

## 👥 کاربران

کارت کاربر: مشخصات، وضعیت، احراز هویت، معرف، موجودی‌ها (با `wallet.view`).

| دکمه | کار | دسترسی |
|---|---|---|
| ⛔️ مسدود کردن / ✅ رفع مسدودی | دلیل الزامی است؛ کاربر مسدود دیگر نمی‌تواند با ربات کار کند | `users.block` |
| ✉️ ارسال پیام | پیام مستقیم از طرف مدیریت | `users.edit` |
| ➕➖ اصلاح موجودی | `+50000 دلیل` یا `-20000 دلیل` ← تأیید | `wallet.adjust` |
| 📒 تراکنش‌ها | Ledger کاربر با موجودی قبل و بعد | `wallet.view` |
| 🛒 / 👥 / 📢 | سفارش‌ها، زیرمجموعه‌ها، کانال‌های کاربر | `orders.view` / `referrals.view` / `channels.view` |

> اصلاح موجودی همیشه یک ردیف `admin_adjustment` در Ledger و یک ردیف Audit (با موجودی قبل و بعد و دلیل) می‌سازد و به کاربر اطلاع داده می‌شود. مبلغِ اضافه‌شده قابل خرج است ولی **قابل برداشت نیست** (مثل واریز درگاه).

## 📣 کمپین‌ها

چرخه: `draft` (پرداخت‌نشده) ← `pending` ← `active` ← `completed` / `cancelled` / `expired` / `rejected`

| عمل | نتیجه |
|---|---|
| ✅ تأیید | کمپین فعال و برای ناشران قابل مشاهده می‌شود؛ مهلت از همین لحظه شروع می‌شود |
| ⛔️ رد (با دلیل) | کل مبلغ به تبلیغ‌دهنده برمی‌گردد |
| ⏸ توقف / ▶️ ادامه | Joinهای جدید شمرده نمی‌شوند / دوباره شمرده می‌شوند |
| 🚫 لغو | بودجه‌ی مصرف‌نشده برمی‌گردد؛ لینک‌ها باطل می‌شوند |
| 🏁 تکمیل | بستن زودهنگام به‌عنوان تکمیل‌شده؛ بودجه‌ی مصرف‌نشده برمی‌گردد |
| ✏️ ویرایش | عنوان و توضیحات |
| ➕ ثبت پیشرفت | فقط کمپین‌های دستی (پست، بازدید، فوروارد، ری‌اکشن، سفارشی) |
| 🔗 لینک‌ها | ورود/خروج و امتیاز ریسک هر ناشر؛ تعلیق یا فعال‌سازی لینک |

با `campaign.auto_approve` کمپین‌ها بدون بررسی فعال می‌شوند. اگر ربات از ادمینی کانالی برداشته شود، کمپین فعال آن کانال خودکار متوقف می‌شود.

**🏷 تعرفه‌ها** (در منوی کمپین‌ها): فعال/غیرفعال کردن هر نوع تبلیغ و حداقل قیمت هر واحد.

## 🚨 رفتار مشکوک

| نوع | معنی |
|---|---|
| `fast_leave` | خروج عضو کمتر از `fraud.fast_leave_seconds` پس از ورود |
| `join_burst` | بیش از `fraud.join_burst_count` ورود در `fraud.join_burst_window` ثانیه از یک لینک |
| `repeat_leaver` | حسابی که مکرراً عضو و خارج می‌شود |
| `self_join` | ناشر یا مالک از لینک خودش وارد شده |

امتیازها روی لینک جمع می‌شوند؛ با رسیدن به `fraud.suspend_link_score` لینک خودکار تعلیق و به چت مدیر هشدار داده می‌شود. پس از بررسی «✔️» را بزنید؛ در صورت تقلب، کاربر را مسدود و لینک را در حالت تعلیق نگه دارید (درآمد Pending آن‌ها تا تسویه قابل بازبینی است).

## 💸 برداشت‌ها

1. **در انتظار بررسی** ← جزئیات را باز کنید. مقصد کامل فقط برای مدیرِ دارای `withdrawals.approve` نمایش داده می‌شود (و این مشاهده ثبت می‌شود).
2. 👍 **تأیید** ← (اختیاری) ⚙️ **در حال پرداخت** ← مبلغ «قابل پرداخت» را واریز کنید.
3. ✅ **پرداخت شد** ← کد پیگیری / TX Hash را بفرستید (`-` برای بدون کد). به کاربر اطلاع داده می‌شود.
4. ⛔️ **رد** ← دلیل الزامی؛ مبلغ کامل به کیف پول کاربر برمی‌گردد.

پس از «پرداخت شد» دیگر امکان رد وجود ندارد. قبل از پرداخت، Ledger و سابقه‌ی ریسک کاربر را ببینید.

## 💳 پرداخت‌ها و 🛒 سفارش‌ها

- پرداخت‌ها: وضعیت، Authority / TX Hash، تعداد تأیید و تاریخچه‌ی رویدادهای درگاه. اگر کاربری می‌گوید پرداخت کرده ولی شارژ نشده: «🔄 بررسی مجدد از درگاه». این کار نمی‌تواند دوبار شارژ کند.
- سفارش‌ها: تغییر وضعیت در مسیرهای مجاز و «↩️ Refund» (برای سفارش کمپین = لغو کمپین و برگشت بودجه‌ی مصرف‌نشده).

## 🪪 احراز هویت

درخواست را باز کنید (تصویر مدرک هم ارسال می‌شود)، نام و کد ملی را با مدرک تطبیق دهید ← ✅ تأیید یا ⛔️ رد با دلیل. درخواست‌های بررسی‌نشده پس از `kyc.ttl_days` روز خودکار رد می‌شوند و کاربر می‌تواند دوباره درخواست دهد.

## 🎧 تیکت‌ها

فهرست تیکت‌های منتظر پاسخ ← ✍️ پاسخ (متن یا فایل) / 🔒 بستن. پاسخ شما برای کاربر ارسال می‌شود.

## 📨 پیام همگانی

مخاطب ← محتوا (متن، عکس، ویدیو، فایل، گیف) ← دکمه‌های لینک‌دار (اختیاری) ← پیش‌نمایش ← تأیید.

- ارسال در پس‌زمینه و با رعایت محدودیت تلگرام انجام می‌شود؛ پیشرفت در «📂 تاریخچه» (ارسال‌شده / ناموفق) و امکان «🛑 توقف ارسال».
- کاربرانی که ربات را Block کرده‌اند علامت می‌خورند و در ارسال‌های بعدی نیستند.

## 📤 خروجی

کاربران، سفارش‌ها، تراکنش‌ها، برداشت‌ها و کمپین‌ها به CSV یا Excel. فایل در پس‌زمینه ساخته و برای خود شما ارسال می‌شود. ستون‌های حساس در خروجی نیستند.

## ⚙️ تنظیمات

- گروه‌ها: قابلیت‌ها، سیستم، کمیسیون، کمپین، سفارش، برداشت، انتقال، نرخ، رتبه‌بندی، امنیت. موارد روشن/خاموش با یک لمس؛ بقیه با ارسال مقدار جدید. تغییرات حداکثر تا ۵ ثانیه بعد اعمال می‌شوند و در Audit Log ثبت می‌شوند.
- **حالت تعمیر**: سیستم ← «حالت تعمیر و نگهداری». فقط مدیران می‌توانند با ربات کار کنند.
- **عضویت اجباری**: قابلیت `عضویت اجباری` را روشن و در سیستم ← «کانال‌های عضویت اجباری» نام کانال‌ها را وارد کنید (`@channel1 @channel2`). ربات باید در آن کانال‌ها ادمین باشد.
- **متن‌ها**: «📝 ویرایش متن‌های ربات» ← کلید متن ← متن جدید.

## 🧾 لاگ‌ها

- لاگ‌های امروز به تفکیک کانال: `errors`, `application`, `telegram`, `payment`, `wallet`, `orders`, `campaigns`, `security`, `workers`, `admin`.
- **Audit Log**: همه‌ی عملیات مدیران با زمان و IP.
- کاربر هنگام خطا یک «کد پیگیری» می‌بیند؛ همان کد در ابتدای خط لاگ مربوط آمده است.

## کارهای روزانه‌ی پیشنهادی

1. داشبورد: خطاها، Jobهای ناموفق، Workerها.
2. برداشت‌های در انتظار.
3. کمپین‌های در انتظار تأیید.
4. تیکت‌های باز و درخواست‌های احراز هویت.
5. موارد مشکوک.