# مستندات مرجع اصلی پروژه BVPN
**نسخه سند:** 1.0  
**تاریخ تهیه:** ۱۴۰۵/۰۸/۰۳ (2026-10-25)  
**هدف:** نگهداری یک مرجع قابل‌استفاده برای ادامه توسعه، عیب‌یابی یا بازسازی پروژه BVPN در صورت خرابی فایل‌ها.

> **نکته مهم:** این سند وضعیت شناخته‌شده پروژه و تصمیم‌های تأییدشده را ثبت می‌کند؛ به‌تنهایی جایگزین کدهای PHP، فایل SQL و نسخه پشتیبان دیتابیس نیست. برای بازسازی واقعی، این سند را همراه آخرین ZIP سورس، `schema.sql` و بکاپ دیتابیس نگه دارید.

---

## 1. معرفی پروژه

- **نام:** BVPN
- **نشانی سایت:** `https://gous.ir/bvpn`
- **محیط هاست:** cPanel / LiteSpeed، PHP 8.2.x و MySQL/MariaDB
- **زبان رابط:** فارسی، راست‌چین (`fa`, `dir="rtl"`)
- **سبک موردنظر:** پنل مدیریت تیره و مدرن، داشبوردی شبیه نمونه AquaAdmin؛ پنل کاربر روشن و مینیمال، الهام‌گرفته از نمونه اپ VPN ارسالی.
- **لوگو:** فعلاً لوگوی متنی BVPN با نشان حرف B.
- **تعامل رابط:** CSS و JavaScript، فرم‌های PHP و در موارد لازم AJAX.
- **محدوده نصب:** زیرپوشه `/bvpn`؛ مسیرهای نسبی فایل‌ها باید با همین محل سازگار باشند.

## 2. اصول معماری مورد توافق

1. ماژول `servers-manager` باید مستقل و مرجع اصلی عملیات سرورها باشد.
2. ماژول‌های دیگر نباید مستقیماً SSH اجرا کنند؛ عملیات ساخت، حذف، تمدید، تعلیق، محدودیت و گزارش سرور از طریق bridge/API ماژول Server Manager انجام شود.
3. خطاهای عملیات باید برای مدیر قابل‌فهم باشند و جزئیات فنی در لاگ ثبت شوند.
4. هیچ عملیات سروری نباید فقط بر اساس پیام موفقیت ظاهری تلقی شود؛ خروجی واقعی سرور و نتیجه نهایی باید بررسی شود.
5. پیش از هر جایگزینی فایل روی سایت فعال، از فایل‌ها و دیتابیس بکاپ گرفته شود.
6. فایل‌های پیکربندی محلی، رمزها، کلید API و کلیدهای رمزگذاری نباید در ZIP عمومی یا مستندات ذخیره شوند.
7. نام کاربری و رمز اکانت دستی می‌تواند ترکیبی از حروف و اعداد باشد؛ نام کاربری مبتنی بر موبایل نیز نیاز پروژه است. محدودیت واقعی `useradd` روی لینوکس باید در کد سمت سرور مدیریت شود، نه فقط در اعتبارسنجی PHP.
8. تاریخ‌های نمایشی سایت باید شمسی باشند، اما مقدار تاریخ ذخیره‌شده در دیتابیس و تبادل با سرور باید در قالب استاندارد میلادی/UTC یا قالب مشخص backend باقی بماند؛ تبدیل فقط در مرز نمایش/ورودی انجام شود.

## 3. تصمیم‌های تأییدشده

### سرورها
- سیستم‌عامل قابل‌قبول: Ubuntu 22.04 یا جدیدتر.
- ارائه‌دهنده محدود به DigitalOcean نیست.
- سرور آزمایشی اعلام‌شده: `165.245.249.27`.
- پورت SSH فعلی که کاربر اعلام کرده: `22`.
- کاربر مدیریتی اتصال: `root`.
- رمز سرور عمداً در این سند ذخیره نشده است. رمز قبلاً در گفتگو به اشتراک گذاشته شده؛ پس از پایان آزمایش بهتر است تغییر داده شود.
- پورت هدف: TCP `443`.
- روش تغییر پورت باید مرحله‌ای باشد: ابتدا اجازه‌دادن به 443 در فایروال سیستم و فایروال ارائه‌دهنده، افزودن 443 بدون حذف 22، آزمایش اتصال جدید روی 443، سپس در صورت موفقیت حذف 22. نشست مدیریتی فعلی تا پایان تست باز بماند.
- اتصال PHP به سرور از طریق SSH با `phpseclib3` یا افزونه PHP `ssh2`.
- نیازمندی‌های عملیاتی: ساخت/حذف/تعلیق/تمدید حساب، تعیین حجم دانلود، تاریخ انقضا، میزان دانلود و آپلود، تعداد نشست‌های آنلاین، زمان اتصال و قطع و لاگ نشست‌ها. ثبت IP و مدل گوشی کاربر لازم نیست.
- حدود اتصال هم‌زمان:
  - `admin`: پنج اتصال
  - `user`: پنج اتصال
  - `vip`: ده اتصال
  - `special` / «ویژه»: ده اتصال
  - `gift` / «هدیه»: دو اتصال
- حساب تست: یک روز.
- حجم پیش‌فرض هر کاربر: 200 GiB؛ این مقدار باید در پنل مدیریت قابل تنظیم باشد و در پروفایل عادی کاربر نمایش داده نشود.
- نمونه‌برداری `nethogs` فعلاً آزمایشی است؛ پیش از استفاده برای قطع خودکار یا محاسبه مالی باید با انتقال کنترل‌شده اندازه‌گیری و صحت‌سنجی شود.

### کاربران و عضویت
- گروه‌ها: `admin`, `user`, `vip`, `special`, `gift`.
- کاربر پرداخت‌کننده عادی: `user`.
- کاربر تست: `gift`.
- گروه‌های `admin`, `vip`, `special` توسط مدیر انتخاب می‌شوند.
- کد معرف چهاررقمی است.
- نام کاربری/رمز خودکار مبتنی بر موبایل در طراحی اولیه با پیشوند `ir` تعریف شده است؛ برای مثال `ir09123456789`. در افزودن دستی، نام کاربری و رمز باید دستی قابل تعیین باشند.
- ثبت‌نام با کد معرف، شماره موبایل و OTP پیامکی طراحی شده است.
- OTP واقعی نیازمند تنظیمات معتبر IPPanel است.
- حساب‌های تست دیتابیس که در نسخه‌های راهنما ذکر شده‌اند:
  - `admin` / `admin`
  - `arshia` / `arshia`
  این‌ها صرفاً برای آزمایش‌اند و باید پیش از استفاده عمومی تغییر کنند.

### پرداخت و قیمت
- واحد قیمت در پنل: تومان.
- مقدار ارسالی به زیبال: ریال، یعنی تومان × 10.
- درگاه: زیبال.
- تنظیم مرچنت به‌تنهایی اثبات نمی‌کند که پرداخت فعال است؛ ایجاد درخواست، بازگشت callback، اعتبارسنجی نتیجه و ثبت پرداخت باید end-to-end آزمایش شوند.
- تمدید ماهانه هدف‌گذاری‌شده: 31 روز به تاریخ انقضا اضافه شود.
- تمدید آنلاین و ثبت دستی پرداخت باید در جدول پرداخت و سوابق کاربر قابل مشاهده باشند.

### پیامک
- سرویس موردنظر: IPPanel و الگوی Pattern.
- پترن‌های موردنیاز: OTP ثبت‌نام/ورود، ایجاد اکانت، فعال‌شدن اکانت، فعال‌کردن هدیه، خرید موفق، انقضا و یادآوری 5 روز مانده و روز آخر.
- هر پترن باید در پنل قابل تنظیم باشد؛ شامل کد پترن و متغیرهای آن.
- نمونه متغیرهای خرید: `%name%`, `%mablagh%`, `%paydate%`, `%ordernumber%`.
- ارسال پیامک تا زمانی که API Key، شماره فرستنده و کد پترن واقعی تنظیم و با پیام آزمایشی تأیید نشده، عملیاتی محسوب نمی‌شود.

### رابط کاربری
- مدیریت: تم تیره، منوی کناری راست، داشبورد، کارت‌های آماری، جدول‌ها و نمودار فروش.
- کاربر: تم روشن، خلاصه اشتراک، مصرف، انقضا، پروکسی‌ها، کد معرف، فاکتورها و لاگ‌های اتصال.
- در موبایل، منو و جدول‌ها باید واکنش‌گرا باشند.
- تقویم‌های قابل مشاهده برای کاربر/مدیر شمسی باشند؛ تاریخ خام ذخیره‌شده در دیتابیس نباید به‌صورت تصادفی تبدیل و دوباره ذخیره شود.

## 4. ساختار فایل‌ها و مسئولیت‌ها

ساختار هدف/شناخته‌شده پروژه:

```text
bvpn/
├── index.php                 # صفحه لندینگ، ورود و ورود به عضویت با کد معرف
├── login.php                 # ورود و خروج
├── register.php              # عضویت و OTP
├── profile.php               # پروفایل کاربر
├── database.php              # اتصال PDO و توابع مشترک
├── admin.php                 # پنل مدیریت و مسیرهای اصلی مدیریت
├── statitics.php              # گزارش/آمار مدیریتی (املای فایل فعلاً همین است)
├── support.php                # صفحه پایه پشتیبانی
├── config.php                 # تنظیمات محلی محرمانه؛ نباید عمومی یا در ZIP منتشر شود
├── config.example.php         # نمونه تنظیمات، اگر در نسخه جاری وجود داشته باشد
├── schema.sql                 # طرح اولیه دیتابیس
├── .htaccess                  # قواعد دسترسی/بازنویسی
├── assets/
│   ├── style.css              # استایل اصلی
│   ├── app.js                 # رفتارهای عمومی
│   └── dashboard.js           # رفتارهای داشبورد در نسخه‌های مربوط
├── admin/
│   ├── actions/               # عملیات جداشده مدیریت، در صورت وجود در نسخه نصب‌شده
│   └── pages/                 # صفحات مدیریت، در صورت وجود در نسخه نصب‌شده
├── members/                   # صفحات/ابزارهای کاربری
├── servers-manager/
│   ├── public/                # رابط و API ماژول مستقل
│   ├── app/
│   │   ├── SshService.php     # ارتباط SSH
│   │   ├── bootstrap.php
│   │   ├── helpers.php
│   │   └── site_bridge.php    # اتصال محدود ماژول به سایت اصلی
│   ├── config/config.php      # تنظیمات محلی ماژول؛ کلید باید اختصاصی باشد
│   ├── server/
│   │   ├── install-agent.sh   # نصب عامل سمت Ubuntu
│   │   └── usage_collector.py # نمونه‌برداری مصرف
│   ├── storage/
│   │   ├── servers.json       # اطلاعات سرورها/اعتبارنامه رمزگذاری‌شده در نسخه‌های مربوط
│   │   └── manager.log        # لاگ ماژول
│   ├── tests/
│   ├── composer.json
│   └── README_FA.md
├── payments/
│   ├── create.php             # ایجاد درخواست پرداخت
│   ├── callback.php           # callback زیبال
│   └── README_FA.md
├── sms/
│   ├── ippanel.php
│   └── README_FA.md
├── telegram-bot/
│   └── README_FA.md           # وضعیت/راهنمای ربات
├── sql/
│   ├── fix_admin_login.sql
│   ├── fix_admin_login_v07.sql
│   └── dashboard_upgrade_v1.sql
├── docs/
│   └── BVPN_System_Guide_FA.md
└── inclouds/                  # محل افزونه‌های آینده (نام پوشه مطابق خواسته پروژه)
```

**هشدار درباره تفاوت نسخه‌ها:** تمام فایل‌های بالا لزوماً در همه ZIPها یا روی هاست وجود ندارند. قبل از جایگزینی، فهرست واقعی `public_html/bvpn` را با این ساختار مقایسه کنید. نام‌هایی مثل `config/local.php` و `config/bootstrap.php` در بعضی اصلاحیه‌های قدیمی استفاده شده‌اند، در حالی که نسخه‌های دیگر `config.php` و `database.php` در ریشه دارند. این دو الگو را بدون بررسی فایل‌های واقعی با هم ترکیب نکنید.

## 5. دیتابیس و جدول‌های شناخته‌شده

در `schema.sql` نسخه مرجع رابط کاربری، جدول‌های زیر تعریف شده‌اند یا در کد به آن‌ها ارجاع داده شده است:

- `users`: نام کاربری، موبایل، هش رمز، گروه، وضعیت، کد معرف، معرف بالادستی، سقف مصرف، تاریخ انقضا و زمان ایجاد.
- `servers`: نام، IP/host، پورت، کاربر SSH، شناسه اعتبارنامه، وضعیت و زمان آخرین بررسی.
- `subscriptions`: اشتراک، مبلغ، وضعیت، شروع و پایان.
- `payments`: شماره سفارش، ارائه‌دهنده، مبلغ تومان/ریال، شناسه رهگیری، وضعیت و زمان پرداخت.
- `otp_codes`: شماره موبایل، هدف OTP، هش کد، انقضا و تعداد تلاش.
- `settings`: کلید و مقدار تنظیمات.
- `telegram_proxies`: لینک پروکسی، برچسب، وضعیت و سازنده.
- `audit_logs`: ثبت عملیات مدیر و تغییرات.
- `connection_events`: رویدادهای اتصال/قطع/انقضا و زمان وقوع.
- `traffic_usage` و/یا `server_user_usage`: داده‌های مصرف؛ نام دقیق جدول باید با schema نصب‌شده تطبیق داده شود.
- ممکن است جدول‌های تکمیلی مانند `referral_codes`, `user_groups`, `admins` یا جدول‌های گزارش/همگام‌سازی در اصلاحیه‌های نسخه‌های مختلف وجود داشته باشند.

**مهم:** تاریخچه پروژه شامل چند نسخه با طرح دیتابیس متفاوت بوده است؛ در بعضی خطاها جدول `user_groups` وجود نداشته و در نسخه‌ای دیگر گروه مستقیماً در `users.role` بوده است. بنابراین پیش از اجرای SQL اصلاحی، از دیتابیس بکاپ بگیرید و `SHOW TABLES` و ستون‌های واقعی را بررسی کنید. فایل SQL مربوط به نسخه‌ای دیگر را کورکورانه وارد نکنید.

## 6. وضعیت کنونی شناخته‌شده (آخرین گزارش کاربر)

### رابط کاربری
- کاربر گزارش کرده که پس از اصلاحات تقویم/استایل، ظاهر داشبورد مدیریت و صفحه لندینگ به‌هم ریخته و پروفایل کاربر بدون استایل یا با چیدمان ناقص نمایش داده می‌شود.
- اسکرین‌شات‌ها نشان می‌دهند بعضی متن‌ها و منوها به هم چسبیده‌اند یا محتوا در سمت راست فشرده شده است.
- یک بسته با نام `BVPN_UI_Recovery_v1.zip` تحویل شده که برای برگرداندن استایل/چیدمان از نسخه قبلی رابط کاربری ساخته شده است.
- فایل‌های آن بسته: `admin.php`, `profile.php`, `index.php`, `support.php`, `statitics.php`, `assets/style.css`, `assets/app.js` و راهنمای نصب.
- **این بسته را قبل از نصب با بکاپ مقایسه کنید.** چون از یک نسخه قبلی رابط گرفته شده، ممکن است بخشی از قابلیت‌هایی را که بعداً اضافه شده‌اند به عقب برگرداند. آن را روی سایت زنده بدون بکاپ جایگزین نکنید.
- پس از هر تغییر CSS، هر سه صفحه `admin.php`, `profile.php`, `index.php` باید جداگانه روی دسکتاپ و موبایل بررسی شوند.

### مدیریت سرور و ساخت کاربر
- سرور آزمایشی در ماژول Server Manager ثبت شده و کاربر گفته است ابزار تا حدی کار می‌کند.
- در اتصال سایت اصلی به سرور مشکل همگام‌سازی/ساخت کاربر گزارش شده است.
- خطای واقعی گزارش‌شده از Ubuntu:
  `useradd: invalid user name '09190330997': use --badname to ignore`
- این نشان می‌دهد اعتبارسنجی PHP به‌تنهایی کافی نیست؛ اسکریپت سمت Ubuntu نیز نام کاربری عددی را رد می‌کند. باید تصمیم آگاهانه‌ای در عامل سرور گرفته شود: یا افزودن گزینه مناسب `useradd --badname` پس از اعتبارسنجی سخت‌گیرانه ورودی، یا تبدیل نام کاربری به قالب مجاز مثل پیشوند `ir`. چون کاربر صریحاً خواسته نام کاربری می‌تواند شماره موبایل باشد، رفتار نهایی باید مطابق همان تصمیم پیاده‌سازی و روی Ubuntu واقعی تست شود.
- یک خطای دیگر از نسخه قبلی عامل نشان می‌داد اعتبارسنجی `bvpnctl` فقط الگوی شروع با حرف/زیرخط را می‌پذیرد. اصلاح باید در تمام مسیرهای create/delete/renew/suspend/limit و در bridge انجام شود، نه فقط یک فرم.
- گزارش سرور در پنل اصلی کامل و قابل اتکا تلقی نمی‌شود تا زمانی که داده Server Manager با جدول‌های سایت هماهنگ شود.

### پرداخت
- تنظیم مرچنت در پنل دیده شده، اما کاربر گزارش کرده مسیر واضحی برای پرداخت وجود ندارد و هنوز مشخص نیست درگاه end-to-end کار می‌کند.
- تست لازم: ساخت فاکتور/سفارش، رفتن به زیبال، بازگشت callback، بررسی مبلغ ریالی، ثبت `paid` و تمدید اشتراک دقیقاً 31 روز.
- تا انجام تست واقعی، پرداخت را «پیکربندی‌شده اما تأییدنشده» در نظر بگیرید.

### پیامک
- کاربر گزارش کرده بخش تنظیمات پیامک در پنل وجود ندارد یا کار نمی‌کند.
- فرم عضویت قبلاً خطایی نشان داده که `api_key`, شماره فرستنده و `sms.enabled` در تنظیمات لازم‌اند.
- هدف نهایی این است که کدهای پترن و متغیرها از داخل پنل مدیریت تنظیم شوند، نه اینکه برای هر تغییر دستی فایل PHP ویرایش شود.
- تست لازم: ارسال OTP واقعی به شماره تحت کنترل کاربر، تأیید کد، ایجاد حساب، سپس تست پترن خرید و انقضا. لاگ نباید API Key یا کد OTP را افشا کند.

### بخش‌های دیگر
- پروکسی تلگرام: باید مدیر بتواند تعداد نامحدود لینک اضافه کند و کاربران بتوانند هر لینک را کپی کنند.
- معرف‌ها: کد چهاررقمی، تعداد ثبت‌نام‌ها و خریداران و مرتب‌سازی بر اساس ستون‌ها.
- پشتیبانی: فعلاً صفحه پایه/دمو.
- VLESS، تونل و سایر کانفیگ‌ها: بخش آینده؛ تا زمان تکمیل باید غیرفعال یا با برچسب «در حال توسعه» نمایش داده شوند.
- ربات تلگرام: فعلاً اسکلت/مستندات اولیه؛ هنوز نباید قابلیت‌های تکمیل‌نشده را عملیاتی معرفی کرد.
- تقویم شمسی: نیازمند اصلاح یکپارچه و تست در همه فرم‌ها، فیلترها، فاکتورها و تاریخ‌های انقضاست.

## 7. مسیرهای موردنظر در پنل

### صفحه اصلی
- معرفی BVPN و لینک ورود.
- ورود کاربر.
- عضویت پس از واردکردن کد معرف چهاررقمی.
- لوگوی متنی موقت.
- پس از ورود، دسترسی به پروفایل و خروج؛ برای مدیر، لینک پنل مدیریت.

### پنل کاربر
- خلاصه وضعیت حساب، تاریخ عضویت، آخرین به‌روزرسانی مصرف، تاریخ انقضا و روزهای باقی‌مانده.
- نمایش دانلود و آپلود در واحد مناسب.
- تعداد نشست‌های هم‌زمان و لاگ‌های اتصال/قطع؛ صفحه‌بندی 10 رویداد در هر صفحه با فیلتر تاریخ.
- یادآوری تمدید در پنج روز پایانی و روز آخر؛ پیامک‌ها از تنظیمات قابل کنترل باشند.
- تمدید یک‌ماهه، پرداخت و فاکتور/شماره رهگیری.
- کد معرف قابل کپی و تعداد افراد عضو/خریدار.
- پروکسی‌های تلگرام قابل کپی.
- دکمه پشتیبانی و خروج.
- سقف مصرف واقعی در پروفایل عادی مخفی بماند.

### پنل مدیریت
- داشبورد تیره با منوی راست و چیدمان واکنش‌گرا.
- خلاصه اتصال سرورها، میزان مصرف، تعداد کاربران آنلاین، آمار فروش آنلاین/دستی در روز/هفته/ماه/سال.
- مدیریت سرورها: افزودن، تست اتصال، نصب مانیتورینگ، بازکردن پورت، تغییر پورت، همگام‌سازی، مشاهده لاگ و نتیجه هر عملیات.
- مدیریت کاربران: جدول قابل مرتب‌سازی و صفحه‌بندی 30 ردیف، مشاهده جزئیات، تغییر رمز/گروه/انقضا/حجم، تمدید، تعلیق، حذف، افزودن پرداخت دستی و مشاهده پروفایل از دید کاربر.
- گزارش مدیر: ثبت عملیات مدیر با زمان و هدف.
- پروکسی تلگرام، معرف‌ها، تنظیمات پرداخت، تنظیمات پیامک، پشتیبانی، کانفیگ‌ها و ربات تلگرام.
- تنظیمات حساس فقط در محیط تنظیمات مجاز ذخیره شوند و در لاگ/HTML نمایش داده نشوند.

## 8. ربات تلگرام — نسخه اول موردنظر
- مدیریت ربات از پنل مدیریت.
- دستورات مدیر و کاربر مجزا باشند.
- نسخه اول:
  1. ساخت حساب: درخواست نام کاربری، رمز، تکرار رمز؛ سپس نتیجه واقعی ساخت روی سایت و سرورها.
  2. مشاهده مصرف کاربر: نام کاربری، دانلود، آپلود و تاریخ انقضا.
- ربات تا وقتی توکن، webhook/مسیر دریافت آپدیت، مجوزها و عملیات سرور تست نشده‌اند، عملیاتی محسوب نمی‌شود.

## 9. وابستگی‌ها و پیکربندی

### PHP روی هاست
طبق بررسی قبلی کاربر، PHP 8.2.34، SAPI از نوع LiteSpeed و افزونه‌های `PDO`, `pdo_mysql`, `mysqli`, `session` در صفحه بررسی فعال دیده شده‌اند. این فقط نشان می‌دهد آن handler افزونه‌ها را می‌بیند؛ خطاهای دیگر ممکن است همچنان از schema، مسیر config یا کد باشد.

پیش‌نیازهای اصلی شناخته‌شده:
- PHP 8.2+
- PDO MySQL
- cURL، OpenSSL، JSON، Sessions
- `phpseclib3` در `vendor/` یا افزونه `ssh2`
- MySQL/MariaDB
- HTTPS
- دسترسی نوشتن محدود برای `servers-manager/storage/`

### فایل تنظیمات
- نسخه‌های مختلف از `config.php` در ریشه یا `config/local.php` / `config/bootstrap.php` استفاده کرده‌اند. باید با `require` واقعی در `login.php`, `database.php`, `admin.php` مشخص شود کدام الگو روی هاست فعال است.
- تنظیمات دیتابیس، درگاه و پیامک باید فقط در فایل تنظیمات محلی یا جدول تنظیمات مدیریت‌شده باشند.
- کلید رمزگذاری `servers-manager/config/config.php` باید منحصر به همان نصب باشد و بکاپ امن آن جداگانه نگهداری شود.
- رمز SSH و کلید API نباید داخل مستندات ثبت شوند.

## 10. روال امن پشتیبان‌گیری و بازسازی

### پیش از هر تغییر
1. از `public_html/bvpn` یک ZIP کامل بگیرید.
2. از دیتابیس از طریق phpMyAdmin > Export یک خروجی SQL بگیرید.
3. از `servers-manager/storage/servers.json` و `servers-manager/config/config.php` بکاپ محرمانه بگیرید؛ این فایل‌ها ممکن است حاوی اطلاعات اتصال/کلید باشند و نباید عمومی شوند.
4. نسخه‌های فایل و تاریخ بکاپ را در نام فایل درج کنید.
5. یک نسخه خارج از هاست نیز نگه دارید.

### بازسازی در صورت خرابی کامل
1. یک پوشه آزمایشی بسازید یا از هاست/بکاپ سالم بازیابی کنید؛ روی نسخه زنده مستقیماً بازنویسی نکنید.
2. سورس کامل همان نسخه را Extract کنید.
3. دیتابیس را از بکاپ همان نسخه بازیابی کنید. اگر دیتابیس موجود است، قبل از Import دوباره، ساختار و داده‌ها را بررسی کنید.
4. تنظیمات محلی را از نسخه محرمانه بازیابی کنید؛ اگر رمزها/کلیدها افشا شده‌اند، آن‌ها را عوض کنید.
5. وابستگی SSH را از وجود `servers-manager/vendor/autoload.php` یا افزونه `ssh2` بررسی کنید.
6. با ورود مدیر و کاربر تست شروع کنید.
7. تست‌ها را به ترتیب بخش 11 اجرا کنید.
8. پس از موفقیت در محیط آزمایشی، نسخه را با بکاپ جدید روی مسیر اصلی منتشر کنید.

### فایل‌هایی که باید همیشه کنار این سند نگهداری شوند
- ZIP کامل سورسِ نسخه‌ای که روی سایت نصب است.
- خروجی دیتابیس SQL همان تاریخ.
- `config.php` و `servers-manager/config/config.php` به‌صورت رمزگذاری‌شده/محرمانه.
- `servers-manager/storage/servers.json` و لاگ لازم برای عیب‌یابی.
- این سند.
- آخرین گزارش خطاهای cPanel و نسخه PHP فعال.

## 11. چک‌لیست تست بعد از هر نصب/بازسازی

### سایت و رابط
- [ ] صفحه `index.php` بدون خطای PHP باز شود.
- [ ] صفحه `login.php` باز شود و ورود مدیر/کاربر کار کند.
- [ ] پنل مدیریت در دسکتاپ و موبایل منوی مرتب داشته باشد.
- [ ] پروفایل کاربر در تم روشن و بدون چسبیدن متن‌ها نمایش داده شود.
- [ ] CSS و JavaScript از مسیرهای `/bvpn/assets/...` بارگذاری شوند.
- [ ] تاریخ‌ها در ورودی/نمایش شمسی باشند و مقدار دیتابیس درست باقی بماند.

### دیتابیس و کاربران
- [ ] اتصال PDO موفق باشد.
- [ ] جدول‌ها و ستون‌های موردنیاز نسخه با schema نصب‌شده هماهنگ باشند.
- [ ] افزودن کاربر در سایت خطای قابل‌فهم بدهد و گزارش عملیات ثبت شود.
- [ ] نام کاربری عددی/موبایلی با تصمیم نهایی پذیرفته شود.
- [ ] گروه و سقف اتصال مطابق نقش انتخاب‌شده ذخیره شود.

### Server Manager / Ubuntu
- [ ] تست SSH روی پورت فعلی موفق شود.
- [ ] نصب عامل مانیتورینگ بدون خطا انجام شود.
- [ ] ساخت کاربر در Ubuntu واقعاً موفق شود و کاربر در `getent passwd` دیده شود.
- [ ] نشست آزمایشی واقعی از کلاینت برقرار و قطع شود و لاگ ایجاد شود.
- [ ] محدودیت هم‌زمانی برای هر گروه عملاً آزمایش شود.
- [ ] دانلود و آپلود کنترل‌شده با گزارش مصرف مقایسه شود.
- [ ] انقضا و تمدید روی سرور و سایت هماهنگ شوند.
- [ ] پیش از حذف پورت 22، اتصال جدید روی 443 آزمایش شود.

### پرداخت و پیامک
- [ ] OTP واقعی ارسال و تأیید شود.
- [ ] درخواست پرداخت به زیبال هدایت شود.
- [ ] callback پرداخت موفق/ناموفق آزمایش شود.
- [ ] مبلغ تومان/ریال درست باشد.
- [ ] تمدید موفق 31 روز به تاریخ معتبر اضافه کند.
- [ ] پترن خرید موفق و پیام یادآوری انقضا با متغیرهای درست ارسال شوند.

## 12. ترتیب پیشنهادی ادامه توسعه

1. **تثبیت نسخه:** بکاپ کامل فایل‌ها و دیتابیس و مشخص‌کردن دقیق نسخه نصب‌شده.
2. **بازیابی رابط:** مقایسه بسته `BVPN_UI_Recovery_v1.zip` با فایل‌های زنده؛ انتخاب بخش‌های لازم بدون عقب‌گرد ناخواسته قابلیت‌ها.
3. **تثبیت ساخت کاربر روی سرور:** اصلاح اعتبارسنجی نام کاربری در PHP، bridge و `bvpnctl`; آزمایش شماره موبایل روی Ubuntu واقعی.
4. **اتصال داده‌های سرور به داشبورد:** وضعیت، مصرف و کاربران آنلاین از منبع واقعی Server Manager بیاید؛ در صورت نبود داده، صریحاً «داده موجود نیست» نمایش داده شود، نه عدد ساختگی.
5. **تنظیمات پیامک از پنل:** ذخیره کد پترن‌ها و متغیرها در تنظیمات دیتابیس و تست OTP.
6. **پرداخت end-to-end:** فرم تمدید، ایجاد سفارش، callback و ثبت فاکتور.
7. **تقویم شمسی یکپارچه:** فقط پس از تثبیت CSS، با آزمون تمام صفحات.
8. **ربات تلگرام نسخه اول.**
9. **تست نهایی و مستندسازی نسخه انتشار.**

## 13. خطاهای مهمی که قبلاً دیده شده‌اند

- `Class "PDO" not found`: در آن زمان صفحه بررسی PHP نشان داد PDO و `pdo_mysql` فعال‌اند؛ پس بعد از آن باید خطای جدید واقعی و handler مربوط بررسی شود.
- `Table 'gous_bvpn.user_groups' doesn't exist`: کد و دیتابیس از دو نسخه متفاوت بوده‌اند؛ قبل از اجرای اصلاحیه، schema واقعی باید بررسی شود.
- `نام کاربری نامعتبر`: اعتبارسنجی در یک یا چند لایه هنوز با نیاز نام کاربری موبایلی سازگار نبوده است.
- `useradd: invalid user name '09190330997'`: خود Ubuntu نام عددی را رد کرده است؛ تغییر فرم PHP به‌تنهایی کافی نیست.
- تنظیمات SMS درخواست `api_key`, شماره فرستنده و `sms.enabled` داشته است؛ اما هدف نهایی تنظیم از پنل مدیریت است.
- صفحه ورود گاهی 500 داده؛ در آن حالت باید جدیدترین خطا پس از تکرار دقیق عملیات بررسی شود، نه خطای قدیمی.
- ظاهر پنل پس از اصلاح تقویم/CSS خراب شده است؛ هر تغییر رابط باید به‌صورت کوچک، با بکاپ و تست هر سه صفحه اصلی انجام شود.

## 14. وضعیت قطعیت

### مشخص/تأییدشده از تصمیم‌های کاربر
- دامنه و مسیر استقرار.
- PHP 8.2+.
- سرور Ubuntu 22+ و هدف پورت 443.
- گروه‌ها و سقف اتصال.
- کد معرف چهاررقمی.
- تومان در پنل و ریال برای زیبال.
- نیاز به مدیریت SMS، پرداخت، پروکسی، معرف، ربات و گزارش اتصال.
- نیاز به حفظ تاریخچه و جلوگیری از تغییر بی‌مورد اطلاعات قبلی.

### در بسته‌های پروژه دیده شده، اما نیازمند تطبیق با هاست
- فایل‌ها و جدول‌های ذکرشده در ساختار.
- وجود مسیرهای Server Manager، payments، sms و telegram-bot.
- شکل دقیق تنظیمات و schema؛ چون چند نسخه و اصلاحیه وجود دارد.

### هنوز تأیید عملیاتی نشده
- ساخت کاربر روی تمام سرورها از پنل اصلی.
- جمع‌آوری دقیق مصرف و شمارش نشست‌های واقعی کلاینت‌ها.
- محدودیت اتصال روی کلاینت‌های واقعی.
- قطع خودکار در سقف مصرف.
- پرداخت واقعی زیبال.
- ارسال SMS واقعی از IPPanel.
- ربات تلگرام.
- یکپارچگی کامل تقویم شمسی در تمام صفحات.
- پایدار بودن رابط کاربری نسخه فعلی روی هاست.

---

**قانون اصلی برای ادامه کار:** پیش از نوشتن یا جایگزینی کد، ابتدا این سند و فایل‌های واقعی همان نسخه خوانده شوند؛ سپس بکاپ تهیه شود، تغییر کوچک انجام شود و نتیجه واقعی با لاگ/تست تأیید گردد. از ترکیب فایل‌های دو نسخه متفاوت یا ادعای موفقیت بدون خروجی واقعی خودداری شود.
