# 📘 راهنمای جامع معماری و کارکرد موتور رشد کی‌بوک (Keybook Growth Suite)

این مستند به طور دقیق پاسخ سوالات ساختاری شما درباره نحوه اتصال کاربران واقعی، داشبورد شاخص‌ها در نسخه لوکال، سیستم انتخاب کتاب‌های ۳ دعوتی، و ویرایش‌پذیری کتاب‌ها را ارائه می‌دهد.

---

## ۱. چرا در نسخه دانلودی قبلی داشبورد شاخص‌ها مشاهده نمی‌شد؟

در نسخه قبلی، فایل‌های پروژه به صورت جداگانه در پوشه‌های `admin/index.php` و `miniapp/index.php` قرار داشتند؛ اما در **پوشه ریشه (Root)** فایلی به نام `index.php` وجود نداشت. به همین دلیل، هنگامی که شما آدرس لوکال زیر را در مرورگر وارد می‌کردید:

```
http://localhost/keybook-growth/
```

آپاچی در XAMPP صفحه Directory Listing (فهرست پوشه‌ها) یا خطای دسترسی را نشان می‌داد و داشبورد به صورت مستقیم باز نمی‌شد!

### ✅ راه‌حل اعمال‌شده:
1. یک فایل قدرتمند و مستقل به نام `index.php` مستقیماً در ریشه پوشه `keybook-growth/` قرار گرفت.
2. با باز کردن `http://localhost/keybook-growth/`، وضعیت اتصال به دیتابیس MariaDB/MySQL بررسی شده و **کارت‌های شاخص‌های عملکرد (KPIs)** شامل:
   - تعداد کل کاربران واقعی
   - فعال امروز
   - ضریب رشد وایرال (K-Factor)
   - معرفی‌های موفق
   - کتاب‌های مطالعه‌شده
   - امتیازات کی‌پوینت صادر شده
   به صورت بلادرنگ به همراه دکمه‌های ورود مستقیم به پنل مدیریت (`admin/index.php`) و مینی‌اپ کلاینت ایتا (`miniapp/index.php`) به نمایش درمی‌آیند.

---

## ۲. چرا کتاب‌های قفل اکنون ۱۰۰٪ قابل ویرایش و حذف هستند؟

شما کاملاً درست اشاره کردید: **غیرممکن است سیستمی ساخته شود که کتاب قفل‌شده در آن دیگر قابل تغییر نباشد!** شرایط کمپین‌ها، اولویت‌های مدیر و کتاب‌های محبوب مدام تغییر می‌کنند.

### ✅ امکانات مدیریتی اضافه شده (CRUD کامل کتاب‌ها):
- **دکمه ویرایش (Edit Book):** در کنار هر کتاب در پنل مدیریت، دکمه ویرایش قرار دارد. با کلیک روی آن، مدال پیشرفته‌ای باز می‌شود و شما می‌توانید:
  1. عنوان کتاب را تغییر دهید.
  2. نام نویسنده را اصلاح کنید.
  3. **تعداد دعوت‌های لازم برای بازگشایی را کم یا زیاد کنید** (مثلاً از ۳ دعوت به ۲ یا ۵ دعوت).
  4. **قیمت بازگشایی با سکه (KP)** را تعیین کنید (مثلاً ۲۵۰ سکه).
  5. خلاصه کتاب، زمان مطالعه و آدرس تصویر جلد را تغییر دهید.
  6. وضعیت کتاب را بین «🔒 قفل است» و «🔓 باز شده» تغییر دهید.
- **دکمه حذف (Delete Book):** در صورت نیاز می‌توانید هر کتابی را با یک کلیک از لیست حذف نمایید.
- تمام این تغییرات مستقیماً در جدول `locked_books` دیتابیس MySQL ذخیره می‌شوند و بلادرنگ در مینی‌اپ کاربر اعمال می‌گردند.

---

## ۳. سیستم انتخاب کتاب توسط کاربر (اگر ۳ کتاب ۳ دعوت لازم داشته باشند چه می‌شود؟)

این یکی از مهم‌ترین و دقیق‌ترین نکات در گیمیفیکیشن و اقتصاد رفتاری رشد کاربر است:
> **مسئله:** اگر ۳ کتاب جذاب در مینی‌اپ وجود داشته باشند که هرکدام نیازمند ۳ دعوت باشند، کاربر نباید با ۳ دعوت هر ۳ کتاب را یکجا رایگان بگیرد؛ و از طرفی نباید سیستم به صورت تصادفی یکی را به او تحمیل کند.

### ✅ معماری جدید «سهمیه انتخاب آزادانه» (Choice-Based Unlocking):
1. **محاسبه سهمیه (Choice Credits):**
   - کاربر با انجام هر ۳ دعوت موفق، **۱ سهمیه انتخاب کتاب ویژه** دریافت می‌کند.
   - کاربر در مینی‌اپ پیامی مانند زیر مشاهده می‌کند:
     > «🎉 شما ۴ دوست دعوت کرده‌اید و ۱ سهمیه انتخاب کتاب دارید!»
2. **انتخاب آگاهانه کتاب:**
   - کتاب‌های نیازمند ۳ دعوت همگی باز نمی‌شوند؛ بلکه دکمه **«✨ انتخاب این کتاب (سهمیه ۳ دعوت)»** برای آن‌ها فعال می‌شود.
   - کاربر خلاصه و مشخصات کتاب‌ها را بررسی کرده و کتاب دلخواه خود را انتخاب می‌کند.
   - با کلیک کاربر، فقط آن کتاب برای او باز می‌شود (`unlockedBy: 'invites'`).
3. **وضعیت سایر کتاب‌ها:**
   - دو کتاب دیگر نیازمند ۳ دعوت همچنان **قفل** می‌مانند!
   - کاربر متوجه می‌شود که برای باز کردن کتاب دوم:
     - یا باید ۳ دوست دیگر را به ایتا دعوت کند (تا سهمیه بعدی فعال شود)؛
     - یا می‌تواند از **سکه‌های خود (مثلاً ۲۵۰ سکه)** برای بازگشایی فوری آن استفاده کند!
   - این موضوع یک **Growth Loop مداوم** می‌سازد و کاربر پس از رسیدن به هدف اولیه متوقف نمی‌شود.

---

## ۴. آیا کاربران واقعی با دیتابیس MySQL هماهنگ می‌شوند؟

بله؛ موتور رشد کی‌بوک روی معماری مستقل طراحی شده است:
- جدول `users`: تمامی کاربران وارد شده از ایتا با شناسه یکتا ذخیره می‌شوند.
- جدول `growth_events`: تک‌تک رخدادهای باز کردن مینی‌اپ، باز کردن کتاب، اشتراک‌گذاری و تکمیل فصل در این جدول لاگ می‌شوند.
- جدول `referrals`: درخت ارجاع، معرف، کاربر دعوت‌شده و وضعیت خرید آن‌ها در این جدول مدیریت می‌شود.
- جدول `user_unlocked_books`: سوابق کتاب‌های باز شده توسط هر کاربر همراه با روش بازگشایی (`referral_invites` یا `points_exchange`) ثبت می‌گردد.

هنگامی که شما فایل `database.sql` را در phpMyAdmin ایمپورت کنید و پروژه را در لوکال یا سرور مستقر کنید، هر کاربری که از ربات ایتا وارد مینی‌اپ شود فوراً در دیتابیس ثبت شده و شاخص‌های داشبورد به صورت زنده تغییر می‌کنند.

---

## ۵. نقش افزونه وردپرس (keybook-growth-sync.php) چیست؟

این افزونه پل ارتباطی میان فروشگاه ووکامرس شما در وردپرس و موتور رشد کی‌بوک است:
1. هنگامی که یک مشتری در ووکامرس اشتراک یا محصولی را می‌خرد (`woocommerce_order_status_completed`)، افزونه شماره تلفن یا شناسه مشتری را چک می‌کند.
2. اگر آن مشتری توسط یکی از کاربران مینی‌اپ ایتا معرفی شده باشد، افزونه یک وب‌هوک امن با امضای دیجیتال به آدرس `api/wp_webhook.php` ارسال می‌کند.
3. موتور رشد بلافاصله:
   - ۱ ماه اشتراک طلایی جایزه به معرف اعطا می‌کند.
   - ۲۰۰ سکه (KP) به کیف پول معرف می‌افزاید.
   - از طریق وب‌سرویس ایتا، پیام تبریک به همراه لینک مینی‌اپ برای معرف ارسال می‌نماید!
4. هیچ فشاری روی دیتابیس وردپرس ایجاد نمی‌شود و سرعت سایت همواره بالا باقی می‌ماند.

---

## ۶. نحوه اجرای مجدد در XAMPP لوکال‌هاست:

1. فایل زیپ جدید را از دکمه **«دانلود پکیج کامل PHP»** دریافت کنید.
2. محتویات آن را درون پوشه `C:\xampp\htdocs\keybook-growth\` اکسترکت نمایید.
3. در مرورگر آدرس‌های زیر را باز کنید:
   - **پرتال اصلی شاخص‌ها:** `http://localhost/keybook-growth/`
   - **پنل مدیریت پیشرفته و ویرایش کتاب‌ها:** `http://localhost/keybook-growth/admin/`
   - **شبیه‌ساز مینی‌اپ کلاینت ایتا:** `http://localhost/keybook-growth/miniapp/`

---

## ۷. احراز هویت واقعی مینی‌اپ ایتا (Eitaa initData HMAC-SHA256 Signature)

برای جلوگیری از تزریق هویت‌های جعلی (`fake_user_123`) و ساخت حساب‌های کاربری بی‌رویه:
1. مینی‌اپ رشته داده‌های رمزنگاری‌شده `initData` ارسالی از محیط وب‌اپ ایتا را دریافت می‌کند.
2. تابع `verifyEitaaInitData` در سرور با استفاده از کلید `EITAA_BOT_TOKEN` و الگوریتم HMAC-SHA256 صحت امضای هش پارامترها را بررسی می‌کند (`hash_equals`).
3. پارامتر `auth_date` چک می‌شود تا بیش از ۲۴ ساعت نگذشته باشد (جلوگیری قطعی از Replay Attack).
4. در محیط پروداکشن (`APP_ENV = 'production'`) ارسال `initData` معتبر اجباری است و درخواست‌های بدون امضا با خطای ۴۰۱ رد می‌شوند.

---

## ۸. موتور ضدتقلب مطالعه و ضربان قلب سرور-محور (Server-Authoritative Reading Engine)

پیش از این کلاینت می‌توانست با ارسال مستقیم `seconds: 99999` رفرال را واجد شرایط کند یا استریک بگیرد. این نقطه ضعف با معماری نشست سرور کاملاً برطرف شد:
1. **شروع نشست (`start_reading`):**
   - سرور ابتدا بررسی می‌کند آیا کاربر به کتاب دسترسی دارد (کتاب رایگان است، یا اشتراک فعال دارد، یا با سهمیه دعوت/سکه باز شده است).
   - یک `session_token` یکتا و ایمن صادر کرده و زمان شروع نشست را در جدول `reading_sessions` ثبت می‌کند.
2. **ضربان قلب دوره‌ای (`reading_heartbeat`):**
   - کلاینت هر ۲۰ ثانیه توکن نشست را به همراه درصد موقعیت اسکرول ارسال می‌کند.
   - سرور فاصله زمانی سپری‌شده فیزیکی بر اساس ساعت سرور را محاسبه می‌کند (`$now - $lastHeartbeat`).
   - سقف حداکثر ۳۵ ثانیه برای هر بازه اعمال می‌شود و پرش‌های ناگهانی اسکرول مهار می‌گردد.
   - تنها زمانی که ثانیه‌های تاییدشده سرور به ۱۸۰ ثانیه برسد، رفرال کاربر به عنوان «واجد شرایط» (`qualified`) تایید می‌شود.
3. **پایان نشست (`reading_end`):** نشست در سرور بسته می‌شود.

---

## ۹. اعتبارسنجی احراز صلاحیت اتمام کتاب (Anti-Spoof Book Complete)

رویداد `book_complete` دیگر به صورت کورکورانه ۱۲۰ سکه پاداش نمی‌دهد:
- سرور وجود دسترسی به کتاب را بررسی می‌کند.
- جدول `user_book_progress` بررسی می‌شود: کاربر باید حداقل ۱۸۰ ثانیه مطالعه واقعی ثبت‌شده در سرور و حداقل ۹۰٪ پیشرفت اسکرول متن داشته باشد.
- در صورت عدم احراز شرایط، درخواست با خطای شفاف فارسی رد می‌شود.

---

## ۱۰. تضمین Idempotency قطعی در پاداش‌های پله‌ای معرفی (User Tier Claims Table)

برای جلوگیری از اعطای مکرر اشتراک و کتاب در هر بار بررسی پله‌ها:
- جدول اختصاصی `user_tier_claims` با کلید یکتای ترکیبی `UNIQUE KEY (user_id, tier_id)` ایجاد شد.
- تمام انواع پاداش‌ها (سکه، روزهای اشتراک رایگان و کتاب‌های ویژه) ابتدا در این جدول درون تراکنش اتمیک دیتابیس قفل و ثبت می‌شوند و سپس اعمال می‌گردند.
- این امر مانع از هرگونه دریافت دوباره یا خطای Race Condition در شبکه می‌شود.