# Flowها

## ۱. User Flow

```text
/start [ref_xxxxx | c_token]
  └─ Middleware: Rate Limit → Registration (upsert) → Block → Maintenance → Force Join
       └─ منوی اصلی
            ├─ 🛒 سفارش جدید ─ نوع تبلیغ → کانال → عنوان → توضیحات → ظرفیت → قیمت واحد → تأیید
            │       └─ OrderService::create (idempotent) → پرداخت از کیف پول
            │             ├─ موجودی کافی   → Order=paid → Campaign=pending|active
            │             └─ موجودی ناکافی → 💳 شارژ (درگاه) → Callback/Verify → Wallet → پرداخت خودکار سفارش
            ├─ 📢 تبلیغات ─ کمپین‌های فعال → «دریافت لینک اختصاصی» → campaign_links + Telegram Invite Link
            │       └─ Join از لینک → campaign_members → درآمد Pending → (پس از Hold) Available + کمیسیون Referral
            ├─ 📦 سفارش‌های من ─ فعال / تکمیل‌شده / لغوشده / ناموفق → جزئیات → لغو (بازپرداخت)
            ├─ 💰 کیف پول ─ موجودی‌ها، تراکنش‌ها (صفحه‌بندی)، شارژ
            ├─ 💳 امور مالی ─ برداشت، انتقال، حساب بانکی، کیف رمزارز، احراز هویت
            ├─ 📊 گزارش‌ها ─ درآمد امروز/هفته/ماه/کل، Referral، تبلیغات، برداشت‌شده
            ├─ 👥 زیرمجموعه‌گیری ─ لینک، تعداد، درآمد، تاریخچه
            ├─ 🏆 رتبه‌بندی ─ رتبه‌ی من، امتیاز، نفرات برتر
            ├─ 👤 حساب کاربری ─ پروفایل، کانال‌های من
            ├─ 🎧 پشتیبانی ─ تیکت جدید، تیکت‌های من، پاسخ، بستن
            └─ 📚 راهنما / ⚙️ تنظیمات
```

همه‌ی فرآیندهای چندمرحله‌ای `Flow` هستند: State در Redis با TTL نگه‌داری می‌شود، `❌ لغو` State را پاک می‌کند و `🔙 بازگشت` به مرحله‌ی قبل برمی‌گردد.

## ۲. Admin Flow

```text
/admin یا «پنل مدیریت»  (فقط اگر ردیف فعال در admins باشد یا در SUPER_ADMIN_IDS)
  └─ Dashboard (آمار لحظه‌ای + Worker Status)
       ├─ Users      → جستجو → کارت کاربر → Block/Unblock، Wallet، Ledger، Orders، Referral، Channels، پیام
       ├─ Campaigns  → در انتظار → تأیید/رد | فعال → توقف/ادامه/لغو/تکمیل/ویرایش
       ├─ Orders     → فیلتر وضعیت → جزئیات → تغییر وضعیت / Refund / Payment
       ├─ Payments   → فهرست → جزئیات → Verify مجدد
       ├─ Withdrawals→ pending → approve → processing → complete(TX Hash) | reject(دلیل → Refund)
       ├─ KYC / Tickets / Broadcast / Reports / Risk / Export
       └─ Settings / Feature Flags / Admins / Roles / Logs / Health / Maintenance
```

هر اقدام: `Authorizer::authorize(admin, permission)` ← Service ← `AuditLogger` (before/after).

## ۳. Payment Flow

### ZarinPal (ریالی)
```text
PaymentService::create → Gateway.request(amount, callback) → authority
→ کاربر: https://www.zarinpal.com/pg/StartPay/{authority}
→ GET /payment/callback/zarinpal?token=…&Authority=…&Status=OK
→ Gateway.verify(authority, amount)  (code 100 یا 101)
→ PaymentService::confirm  [TX + قفل ردیف + pending→paid + Ledger «payment:{id}»]
→ اگر order_id دارد: OrderService::payFromWallet
```

### NowPayments / Payment4 (رمزارز با واسطه)
```text
create → invoice/payment URL → کاربر پرداخت می‌کند
→ IPN/Callback به /payment/callback/{gateway}  (NowPayments: امضای HMAC-SHA512)
→ همیشه وضعیت دوباره از API درگاه خوانده می‌شود (به بدنه‌ی Callback اعتماد نمی‌شود)
→ confirm (idempotent)
```

### TRON / TON (مستقیم روی زنجیره)
```text
create → مبلغ رمزارز با نرخ لحظه‌ای + پسوند یکتا (TRON) یا Memo یکتا (TON) + آدرس خزانه + انقضا
→ کاربر واریز می‌کند (اختیاری: ارسال TX Hash برای تسریع)
→ VerifyPaymentJob هر ۳۰ ثانیه: خواندن تراکنش از TronGrid / TonCenter
     بررسی: آدرس مقصد، مبلغ ≥ مورد انتظار، Memo، تعداد تأیید ≥ حد، موفق بودن، یکتایی tx_hash
→ confirm (idempotent) | پس از انقضا → expired
```
دریافت TX Hash به‌تنهایی هیچ‌وقت پرداخت را تأیید نمی‌کند.

## ۴. Worker Flow

| Worker (صف) | کار | زمان‌بندی |
|---|---|---|
| `updates` | پردازش Updateهای تلگرام (Dispatcher) | پیوسته |
| `joins` (Join Worker) | `chat_member`: ثبت Join/Leave، ظرفیت، درآمد، Fraud | پیوسته |
| `payments` (Payment Worker) | Verify پرداخت‌های رمزارزی، انقضای پرداخت | پیوسته + هر ۱ دقیقه |
| `orders` (Order Worker) | Fulfil سفارش پرداخت‌شده، لغو سفارش‌های پرداخت‌نشده | پیوسته + هر ۵ دقیقه |
| `campaigns` (Campaign Worker) | تسویه‌ی درآمد Pending، انقضا/تکمیل کمپین، انقضای لینک | هر ۱ دقیقه |
| `withdrawals` (Withdrawal Worker) | انقضای درخواست‌های قدیمی، هشدار صف برداشت | هر ۱۰ دقیقه |
| `broadcast` (Broadcast Worker) | ارسال دسته‌ای با رعایت Rate Limit و FloodWait | پیوسته |
| `notifications` (Notification Worker) | ارسال اعلان رویدادها | پیوسته |
| `statistics` (Statistics Worker) | `daily_stats`، امتیاز و رتبه | هر ۱۰ دقیقه / روزانه |
| `cleanup` (Cleanup Worker) | پاکسازی داده‌ی موقت، KYC منقضی، Stateها | هر ساعت |
| Scheduler | `schedule:run` (Cron هر دقیقه)، Backup شبانه، Health Check هر ۵ دقیقه | Cron |

هر Job: `tries` + Backoff نمایی، لاگ در `storage/logs/workers-*.log`، پس از اتمام Retry در `failed_jobs`. هر Worker هر ۱۰ ثانیه Heartbeat می‌نویسد و پس از N کار یا عبور از سقف حافظه خارج می‌شود تا Supervisor آن را تازه راه‌اندازی کند.