# گزارش تغییرات — 👑 ADVIP کلن (شاپ + پنل مالک)

## درخواست
اضافه‌کردن آیتم «ADVIP» به فروشگاه با قیمت **۱۰۰,۰۰۰ سکه**، به‌همراه امکان
فعال‌سازی/مدیریت آن از پنل مالک ربات. طبق پرامپت بزرگ‌تر قبلی (بخش ۱۵–۱۷)،
ADVIP سقف حمله‌ی روزانه‌ی امپراطوری کلن را بالا می‌برد:
- کلن عادی: حداکثر **۳ حمله در روز**
- کلن ADVIP: حداکثر **۵ حمله در روز**

## ۱) فایل‌های تغییرکرده
- `handlers/clan.php` — ثابت‌های `CLAN_EMPIRE_ATTACKS_NORMAL/ADVIP` + تابع
  `isClanAdvip()` (کاملاً مستقل از `isClanPremium()` که فقط ظرفیت عضویت را
  زیاد می‌کند) + نمایش وضعیت ADVIP در `/clanmy` (پنل «کلن من»).
- `handlers/empire.php` — سیستم قدیمی «۱ حمله در هر ۲۴ ساعت»
  (`empireHasAttackedRecently` + `EMPIRE_WAR_COOLDOWN_HOURS`) حذف و با سقف
  شمارشیِ روزانه جایگزین شد: `empireAttacksToday()` (شمارش از روی
  `empire_wars` با `DATE(created_at) = CURDATE()`، بدون نیاز به ستون/ریست
  دستی) و `empireAttackCap()` (۳ یا ۵ بسته به ADVIP). هر دو نقطه‌ی چک قبلی
  (نمایش وضعیت در شاپ امپراطوری + چک قبل از حمله + چک اتمیک داخل تراکنش با
  `FOR UPDATE`) به همین منطق جدید آپدیت شدند — بدون تغییر در بقیه‌ی منطق
  جنگ/تصرف/اشغال.
- `handlers/shop.php` — ثابت `ADVIP_ITEM` (۱۰۰,۰۰۰ سکه) + دکمه در
  `shopKeyboard()` + شاخه‌ی جدید `kind === 'advip'` در `handleShopCallback()`
  (دقیقاً هم‌الگو با `clanpremium`: فقط مالک کلن می‌تواند بخرد، درخواست به
  پی‌وی مالک(های) ربات فرستاده می‌شود، فعال‌سازی واقعی با `/grantadvip`).
- `handlers/owner_panel.php` — توابع `handleGrantAdvipCommand()` و
  `handleRevokeAdvipCommand()` (هم‌الگو با grant/revokeClanPremium)، و پنل
  «🏰 برترین کلن‌ها» (`owner:clanwar`) حالا وضعیت ADVIP هر کلن (👑ADVIP) و
  راهنمای دستورهای `/grantadvip`، `/revokeadvip` را هم نشان می‌دهد.
- `webhook.php` — روت‌کردن دستورهای متنی جدید `/grantadvip` و `/revokeadvip`.
- `webapp/api/shop.php` — فیلد `advip` (label/price) به JSON خروجی فروشگاه
  وب‌اپ اضافه شد تا با شاپ ربات هماهنگ بماند.
- `webapp/index.html` — بخش «ADVIP» در تب فروشگاه وب‌اپ (کارت نمایشی؛ خرید
  واقعی همچنان فقط داخل ربات انجام می‌شود، دقیقاً مثل بقیه‌ی آیتم‌ها).
- `check_db.php` — ستون جدید `advip_until` به لیست چک‌شونده‌ی جدول `clans`
  اضافه شد.
- `schema.sql` — ستون `advip_until DATETIME NULL` به تعریف جدول `clans`
  برای نصب‌های تازه اضافه شد.

## ۲) Migration جدید
`migrations/add_clan_advip.sql`:
```sql
ALTER TABLE clans ADD COLUMN advip_until DATETIME NULL AFTER premium_until;
```
این migration را یک‌بار روی دیتابیس لایو اجرا کن. اگر خطای
«Duplicate column name» داد یعنی قبلاً اجرا شده، مشکلی نیست.

توجه: برخلاف بخش‌های ۱۵–۱۸ پرامپت اصلی، نیازی به ستون‌های شمارنده‌ی جدا
(«حملات امروز») و منطق ریست دستی نبود — سقف روزانه مستقیم از خودِ جدول
`empire_wars` (که از قبل وجود داشت) با `DATE(created_at) = CURDATE()`
محاسبه می‌شود؛ این هم دیتای تکراری کمتر ایجاد می‌کند و هم با تایم‌زون/تاریخ
فعلی سرور دیتابیس خودکار هماهنگ است.

## ۳) جریان کامل خرید ADVIP
۱. مالک کلن از `/shop` روی «👑 ADVIP کلن — ۱۰۰۰۰۰ سکه» می‌زند.
۲. یک پیام درخواست (با آیدی کلن و دستور آماده‌ی `/grantadvip CLAN_ID 30`)
   به پی‌وی همه‌ی `OWNER_IDS` فرستاده می‌شود (سکه در این مرحله کسر نمی‌شود
   — دقیقاً همان رفتار فعلیِ «کلن پرمیوم»، چون تسویه‌ی خزانه‌ی کلن برای این
   آیتم‌ها دستی و با نظارت مالک انجام می‌شود).
۳. مالک ربات با اجرای `/grantadvip CLAN_ID [روز]` (پیش‌فرض ۳۰ روز) آن را
   فعال می‌کند؛ اگر ADVIP فعلی کلن هنوز منقضی نشده باشد، از تاریخ انقضای
   فعلی جمع زده می‌شود (نه از الان) — دقیقاً همان منطق `grantclanpremium`.
۴. برای لغو: `/revokeadvip CLAN_ID`.

## ۴) سازگاری با سیستم‌های فعلی
- **چیزی حذف نشده**: تمام فیچرهای موجود (کشورها، خرید/فروش کشور، پایتخت،
  اقتصاد، Stability، شورش، ارتش، جنگ، ژنرال‌ها، وزرا، مشاور، مشاغل، XP،
  Reputation، دفترکل خزانه، کلن پرمیوم، بتل‌پس، حراج و...) دست‌نخورده ماندند.
- تنها رفتار موجودی که *تغییر* کرد: سقف حمله‌ی امپراطوری از «۱ حمله در هر
  ۲۴ ساعت» به «۳ (یا با ADVIP: ۵) حمله در روز» تبدیل شد — این دقیقاً همان
  چیزی بود که در پرامپت اصلی (بند ۱۵–۱۷، سیستم ADVIP) درخواست شده بود.
- سطح Atomic/race-condition-safety حمله‌ها حفظ شد: قفل `FOR UPDATE` روی
  ردیف کشور + چک دوباره‌ی سقف روزانه با `FOR UPDATE` داخل همان تراکنش، دقیقاً
  با همان سطح تضمینی که کد قبلی داشت (نه بیشتر، نه کمتر).

## ۵) تست‌های پیشنهادی قبل از انتشار روی دیتابیس لایو
- [ ] اجرای `migrations/add_clan_advip.sql` روی یک کپی از دیتابیس.
- [ ] `php -l` روی همه‌ی فایل‌های تغییرکرده (این محیط به PHP/اینترنت دسترسی
      نداشت، پس این مرحله را حتماً روی سرور خودت قبل از دیپلوی انجام بده).
- [ ] خرید ADVIP از `/shop` با یک کلن تستی → پیام درخواست به مالک می‌رسد.
- [ ] `/grantadvip CLAN_ID 1` → پیام تأیید + اطلاع به اعضا + `/clanmy` سطر
      ADVIP را «فعال» نشان می‌دهد.
- [ ] با کلن ADVIP، ۵ حمله‌ی پشت‌سرهم در همان روز موفق باشد و حمله‌ی ششم با
      پیام «سهمیه تمام شده» رد شود؛ با کلن عادی همین تست با سقف ۳.
- [ ] دو تپ سریع و هم‌زمان روی «حمله» درست قبل از پر شدن سهمیه → فقط یکی
      باید ثبت شود (تست race condition، از دو دیوایس/اکانت یا دو تب موازی).
- [ ] `/revokeadvip CLAN_ID` → سقف کلن به ۳ برمی‌گردد.
- [ ] بعد از گذشتن به روز بعد (یا با تغییر دستیِ `created_at` رکوردهای تست)،
      سهمیه‌ی حمله خودکار ریست شود.