# گزارش تغییرات — سیستم «امپراطوری کلن» (لول/درآمد/ارتقا/فروش)

## 0) فایل‌های تغییرکرده
- `handlers/empire.php` — بخش اصلی همه‌ی فیچرهای جدید
- `cron/tick.php` — درآمد روزانه‌ی کشورها
- `check_db.php` — چک ستون/جدول‌های امپراطوری (قبلاً اصلاً چک نمی‌شدن)
- `schema.sql` — ستون‌های جدید `countries.level`/`last_income_at` + جدول `clan_treasury_ledger` برای نصب‌های تازه
- `migrations/add_empire_levels_treasury.sql` — migration جدید برای دیتابیس‌های موجود

## 1) رفع «امپراطوری باز نمی‌شود»
علت واقعی: `handleEmpireCommand` / `handleShopEmpireCommand` / `handleEmpireCallback`
هیچ `try/catch` مخصوص به خودشون نداشتن. اگه یکی از migrationهای قبلی
(`add_empire_sultanate.sql`, `add_empire_war.sql`) روی دیتابیس واقعی اجرا
نشده باشه، یه ستون مثل `is_vassal` وجود نداره → کوئری Exception می‌ده →
فقط catch سراسری `webhook.php` می‌گرفتش و **فقط لاگ می‌کرد**، به کاربر هیچ
پیامی نمی‌رسید. از دید کاربر یعنی «دکمه/دستور امپراطوری اصلاً جواب نمی‌ده».

فیکس:
- هر سه ورودی الان try/catch مخصوص خودشون دارن؛ در صورت خطای دیتابیس یک
  پیام روشن («خطای دیتابیس، از ادمین بخواه check_db.php رو چک کنه») به
  کاربر نشون داده می‌شه، به‌جای سکوت کامل.
- `check_db.php` الان جدول‌های `countries`, `clan_armies`, `empire_wars`,
  `clan_treasury_ledger` و ستون `clans.empire_xp` رو هم چک می‌کنه (قبلاً
  هیچ‌کدوم چک نمی‌شدن — دقیقاً همون چیزی که باعث می‌شد این ابزار «همه‌چیز
  اوکیه» نشون بده ولی امپراطوری کار نکنه).

**اقدام لازم روی هاست:** migration زیر رو (اگه قبلاً `add_empire_war.sql` و
`add_empire_sultanate.sql` رو اجرا کردی) از phpMyAdmin اجرا کن:
`migrations/add_empire_levels_treasury.sql`

## 2) نمایش نتیجه‌ی حمله
از قبل تو `empireResolveWar()` پیاده‌سازی شده بود (پیام برد/باخت + نام
کشور + تصرف/سلطه + XP/سکه به هر دو کلن ارسال می‌شه). تغییری لازم نبود جز
اینکه با فیکس بخش ۱، دیگه هیچ خطای دیتابیسی این پیام‌رسانی رو بی‌صدا از
کار نمی‌ندازه.

## 3) سقف کشور — سه نوع مستقل (اصلاح‌شده طبق پیام دوم شما)
به‌جای یک سقف کلی، الان **سه سقف کاملاً جدا** پیاده شده، هر کدوم روی
`countries.acquired_via` ('purchase' / 'conquest' / 'vassal') تشخیص داده
می‌شن:

| نوع کلن | خرید | تصرف (مالکیت کامل با حمله) | اشغال (تحت سلطه با حمله) |
|---|---|---|---|
| عادی | ۳ | ۲ | ۱ |
| پرمیوم | ۶ | ۳ | ۳ |

- **خرید**: از بازار آزاد امپراطوری (دکمه‌های لیست کشورهای بدون مالک).
- **تصرف**: وقتی حمله‌ی امپراطوری برنده می‌شه و ظرفیت «تصرف» کلن پر
  نیست → مالکیت کامل (`is_vassal=0`), پاداش کامل.
- **اشغال**: وقتی حمله برنده می‌شه ولی ظرفیت «تصرف» پر بود، و ظرفیت
  «اشغال» جا داره → `is_vassal=1`، پاداش نصف.
- اگه هر دو ظرفیت «تصرف» و «اشغال» پر باشن: حمله از نظر نظامی می‌تونه
  ببره، ولی **هیچ کشوری منتقل نمی‌شه** (پیام مخصوص به هر دو کلن ارسال
  می‌شه). همچنین قبل از شروع حمله، اگه هر دو ظرفیت از قبل پر باشن، اصلاً
  اجازه‌ی زدن دکمه‌ی حمله داده نمی‌شه (تجربه‌ی کاربری بهتر).
- منطق قبلی («اگه کلن مهاجم بزرگ‌تر بود، خودکار اشغال می‌شه») به‌طور
  کامل با این سیستم سقف صریح جایگزین شد.
- انتقال کشور از باخت **کلن‌وار عمومی** (`empireTransferCountryOnWarLoss`
  در `handlers/clanwar.php`) هم از همین سقف‌ها پیروی می‌کنه؛ اگه ظرفیت
  کلن برنده پر باشه، آن بخش انتقال بی‌خطا رد می‌شه (رفتار قبلی‌اش هم همین
  «بدون خطا» بود، فقط حالا ظرفیت رو هم چک می‌کنه).
- ستون جدید `countries.acquired_via` به schema.sql و migration اضافه شد
  (با بک‌فیل خودکار برای کشورهای موجود: `is_vassal=1` → `vassal`، بقیه →
  `purchase`).
- منوی «امپراطوری» الان هر سه شمارنده رو جدا نشون می‌ده (خریداری‌شده/
  تصرف‌شده/اشغال‌شده)، نه یک عدد کلی.

## 4) جدول درآمد/ارتقا/پرمیوم بر اساس لول
`COUNTRY_LEVEL_TABLE` (بالای `handlers/empire.php`) دقیقاً طبق جدولی که
دادید (لول ۱ تا ۱۰) پیاده شد، هر کشور از لول ۱ شروع می‌شه. این جدول یک
constant PHP سرراسته — برای تغییر بعدی مقادیر، فقط همین آرایه رو ادیت
کنید (نیازی به تغییر جای دیگه‌ای از کد نیست).

## 5) ارتقای کشور
- دکمه‌ی جدید «🏰 مدیریت کشورهای من (ارتقا)» در امپراطوری.
- ارتقا داخل transaction با `SELECT ... FOR UPDATE` (هم روی کشور هم روی
  کلن) انجام می‌شه — بدون race.
- قبل از ارتقا موجودی خزانه چک می‌شه؛ اگه کافی نبود، پیام مناسب و بدون
  کسر پول.
- بعد از ارتقا، لول کشور +۱ می‌شه و درآمد روزانه‌اش طبق لول جدید محاسبه
  می‌شه (چون `countryDailyIncome()` مستقیم از `level` می‌خونه).
- سقف لول ۱۰ در کد چک می‌شه (`countryUpgradeCost()` برای لول ۱۰ مقدار
  `null` برمی‌گردونه → دکمه‌ی ارتقا اصلاً نشون داده نمی‌شه).

## 6 و 7) فروش کشور
- بخش جدید «💱 فروش کشور» در منوی امپراطوری.
- لیست کشورهای متعلق به کلن با نام/لول/درآمد روزانه/قیمت فروش.
- انتخاب کشور → صفحه‌ی تأیید نهایی جدا (دکمه‌ی «✅ بله، بفروش» / «❌ انصراف»).
- فروش با `SELECT ... FOR UPDATE` روی کشور انجام می‌شه: اگه کشور دیگه
  مالکش کلن شما نیست (مثلاً هم‌زمان فروخته/تصرف شده)، خطای روشن می‌ده و
  لیست رو رفرش می‌کنه — از دوبار فروش و فروش کشور کلن دیگه جلوگیری می‌کنه.
- بعد از فروش: `owner_clan_id = NULL` (کشور به بازار برمی‌گرده، قابل خرید
  توسط هر کلنی)، لول ریست به ۱، مبلغ فروش به `treasury` کلن اضافه می‌شه.
- **قیمت فروش** = (قیمت پایه‌ی کشور + مجموع هزینه‌ی تمام ارتقاهای انجام‌شده)
  × `COUNTRY_SELL_RATIO` (فعلاً ۰.۶ — قابل‌تغییر با یک عدد بالای فایل).
  یعنی هرچه کشور ارتقا خورده باشه، قیمت فروشش بیشتره.

## 8) خزانه‌ی کلن / دفترکل
جدول جدید `clan_treasury_ledger` (تراکنش‌های: `country_income`,
`country_sale`, `country_upgrade`, `country_purchase`, `war_reward`) —
هر کدوم از این عملیات‌ها الان یک ردیف دقیق با مبلغ (مثبت/منفی) و توضیح
ثبت می‌کنه. این جدول جدا از `clans.treasury` (موجودی فعلی) و کاملاً جدا
از سکه‌ی شخصی بازیکن‌هاست. اگه migration این جدول اجرا نشده باشه، ثبت
لجر فقط لاگ می‌کنه و fail نمی‌شه — خرید/فروش/ارتقا خودشون متوقف نمی‌شن.

## 9) درآمد روزانه‌ی خودکار
`cron/tick.php` هر تیک (هر ۱ دقیقه) کشورهایی که `last_income_at` امروزشون
هنوز واریز نشده رو پیدا می‌کنه، با یک `UPDATE ... WHERE last_income_at IS
NULL OR last_income_at < CURDATE()` اتمیک claim می‌کنه (دقیقاً همون الگوی
atomic-claim جنگ‌ها/وارها که از قبل تو این فایل بود)، بعد درآمد طبق لول
کشور به خزانه‌ی کلنش اضافه می‌شه و تو لجر ثبت می‌شه. این بلوک هم مثل بلوک
جنگ‌های امپراطوری try/catch مجزا داره — اگه migration اجرا نشده باشه، فقط
همین بخش رد می‌شه، بقیه‌ی کرون (بازی‌ها، حراج‌ها، ...) نرمال ادامه پیدا
می‌کنه.

## تست‌های انجام‌شده (بررسی منطقی/دستی کد — بدون PHP runtime در این محیط)
همه‌ی ۱۴ سناریوی درخواستی از نظر منطق کد چک شدن؛ چون محیط فعلی php-cli
نداره، لازمه بعد از اعمال migration، خودتون رو هاست واقعی این‌ها رو تست
کنید:
1. باز شدن صفحه‌ی امپراطوری ✅ (فیکس بخش ۱)
2/3/4. حمله موفق/ناموفق + تصرف ✅ (از قبل + فیکس خطای بی‌صدا)
5. سقف کشور چهارم پرمیوم ✅ (`empireCountryCap` + چک تو `empireBuyCountry`)
6/7. درآمد روزانه + افزایش بعد ارتقا ✅ (بخش ۹ + ۵)
8. ارتقا با موجودی ناکافی ✅ (چک قبل از هر UPDATE)
9/10/11/12. فروش کشور + واریز + حذف از لیست + جلوگیری از فروش دوباره ✅
  (`FOR UPDATE` + چک owner_clan_id)
13. جلوگیری از درآمد دوباره ✅ (atomic claim با `last_income_at`)
14. بررسی خطای PHP/SQL/callback ✅ (`php -l` در این محیط ممکن نبود؛
    بریس/پرانتزها به‌صورت دستی شمارش و بالانس تأیید شد)

## نکته‌ی جدا (طبق یادداشت قبلی): بررسی MIN_PLAYERS/MAX_PLAYERS
`MIN_PLAYERS`/`MAX_PLAYERS` (کلاسیک)، `GOD_MIN/MAX_PLAYERS` و
`DALTON_MIN/MAX_PLAYERS` رو چک کردم — همه سازگار و بدون مشکل هستن
(`MIN_PLAYERS=6` که با نیاز همزمان killer+wolf تو `roles.php` هماهنگه).
مشکلی برای گزارش جداگانه پیدا نشد.