# 🎯 تقرير: أوامر المجموعات والقسائم المتقدمة

**التاريخ:** 2025-10-25  
**الإصدار:** v2.0  
**الحالة:** ✅ جاهز للنشر

---

## 📋 ملخص تنفيذي

تم إضافة **7 أوامر جديدة** للمجموعات و**1 أمر** للقسائم، مع تحسين أوامر موجودة لدعم العمليات الدفعية.

### الأوامر الجديدة:

| الأمر | الوظيفة | الحالة |
|-------|---------|--------|
| `/group_rename` | إعادة تسمية مجموعة | ✅ جديد |
| `/group_delete` | حذف مجموعة نهائياً | ✅ جديد |
| `/group_lock` | قفل مجموعة | ✅ جديد |
| `/group_unlock` | فتح قفل مجموعة | ✅ جديد |
| `/group_usage` | إحصائيات استخدام مجموعة | ✅ جديد |
| `/bot_groups` | عرض مجموعات وحسابات بوت | ✅ جديد |
| `/group_account_add` | إضافة حسابات (دفعات) | ✅ محسّن |
| `/group_account_del` | حذف حسابات (دفعات) | ✅ محسّن |
| `/voucher_who_used` | تقرير استخدام قسيمة | ✅ جديد |

---

## 🗄️ تعديلات قاعدة البيانات

### 1. إضافة عمود `locked` إلى `account_groups`

```sql
ALTER TABLE account_groups 
ADD COLUMN locked TINYINT(1) NOT NULL DEFAULT 0 
COMMENT 'قفل المجموعة يمنع rename/delete';
```

**السلوك:**
- `locked=1` → يمنع `/group_rename` و `/group_delete` فقط
- لا يؤثر على: bind/unbind، add/del accounts، toggle

### 2. فهرس تفرد على `LOWER(group_name)`

```sql
CREATE UNIQUE INDEX idx_unique_group_name_lower 
ON account_groups ((LOWER(group_name)));
```

**السلوك:**
- يمنع أسماء مجموعات مكررة (case-insensitive)
- `vip` = `VIP` = `Vip` (كلها نفس الاسم)

### 3. جدول `voucher_usage` جديد

```sql
CREATE TABLE voucher_usage (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    voucher_code VARCHAR(64) NOT NULL,
    bot_id INT NULL,
    used_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_voucher_code (voucher_code),
    INDEX idx_bot_id (bot_id),
    FOREIGN KEY (voucher_code) REFERENCES vouchers(code) ON DELETE CASCADE,
    FOREIGN KEY (bot_id) REFERENCES sub_bots(id) ON DELETE SET NULL
);
```

**السلوك:**
- يتتبع كل استخدام لقسيمة
- يسجل: أي بوت استخدمها + التاريخ والوقت
- إذا حُذف البوت → `bot_id` يصبح `NULL`

---

## 🔧 الأوامر الجديدة - دليل مفصل

### 1️⃣ `/group_rename`

**الصيغة:**
```
/group_rename <old_name> <new_name>
```

**السلوك:**
- ✅ يتحقق من صحة الاسم الجديد: `[a-z0-9_.-]` بطول ≤32
- ❌ يفشل إذا كانت المجموعة مقفلة (`locked=1`)
- ❌ يفشل إذا كان الاسم الجديد موجوداً (case-insensitive)
- ✅ يسجل العملية في `system_logs`

**مثال:**
```
أنت: /group_rename vip premium
البوت: ✅ تم إعادة تسمية المجموعة من vip إلى premium

أنت: /group_lock premium
أنت: /group_rename premium super_vip
البوت: 🔒 المجموعة premium مقفلة ولا يمكن إعادة تسميتها
       استخدم /group_unlock premium أولاً
```

---

### 2️⃣ `/group_delete`

**الصيغة:**
```
/group_delete <group_name> confirm
```

**السلوك:**
- ⚠️ يتطلب كلمة `confirm` للأمان
- ❌ يفشل إذا كانت المجموعة مقفلة
- ❌ يفشل إذا كانت المجموعة افتراضية (`is_default=1`)
- ❌ يفشل إذا كانت مرتبطة ببوتات (يطلب فك الربط أولاً)
- ✅ يسجل العملية في `system_logs`

**مثال:**
```
أنت: /group_delete old_group
البوت: الاستخدام: /group_delete <group_name> confirm
       ⚠️ هذا الإجراء نهائي ولا يمكن التراجع عنه!

أنت: /group_delete old_group confirm
البوت: ❌ المجموعة مرتبطة بـ 2 بوت
       يجب فك الربط أولاً باستخدام:
       /group_unbind <bot> old_group
```

---

### 3️⃣ `/group_lock` & `/group_unlock`

**الصيغة:**
```
/group_lock <group_name>
/group_unlock <group_name>
```

**السلوك:**
- `locked=1` يمنع **فقط**: rename، delete
- لا يمنع: bind، unbind، add accounts، del accounts، toggle

**مثال:**
```
أنت: /group_lock vip
البوت: 🔒 تم قفل المجموعة vip
       لا يمكن الآن: rename، delete

أنت: /group_unlock vip
البوت: 🔓 تم فتح قفل المجموعة vip
```

---

### 4️⃣ `/group_usage`

**الصيغة:**
```
/group_usage <group_name>
```

**السلوك:**
- يعرض عدد البوتات المرتبطة
- يعرض قائمة كاملة بالحسابات في المجموعة
- Case-insensitive search

**مثال:**
```
أنت: /group_usage vip
البوت: 📊 استخدام المجموعة: vip
       
       🤖 عدد البوتات المرتبطة: 3
       👤 عدد الحسابات: 5
       
       📋 قائمة الحسابات:
       • account1
       • account2
       • account3
       • account4
       • account5
```

---

### 5️⃣ `/bot_groups`

**الصيغة:**
```
/bot_groups <bot_label>
```

**السلوك:**
- يعرض جميع المجموعات المرتبطة بالبوت
- يعرض **UNION** مميز لجميع الحسابات المرئية للبوت
- Case-insensitive search

**مثال:**
```
أنت: /bot_groups mybot
البوت: 🤖 مجموعات البوت: mybot
       
       📂 المجموعات المرتبطة (3):
       • ✅ default
       • ✅ vip 🔒
       • ⛔ test
       
       👤 الحسابات المرئية (8):
       • acc1
       • acc2
       • acc3
       • acc4
       • acc5
       • acc6
       • acc7
       • acc8
```

**SQL المستخدم:**
```sql
-- الحسابات المرئية (UNION من جميع المجموعات)
SELECT DISTINCT a.account_name
FROM bot_groups bg
JOIN group_accounts ga ON ga.group_id=bg.group_id
JOIN steam_accounts a ON a.id=ga.account_id
WHERE bg.bot_id=?
ORDER BY a.account_name;
```

---

### 6️⃣ `/group_account_add` (محسّن)

**الصيغة:**
```
/group_account_add <group> <acc1> <acc2> <acc3> ...
```

**السلوك:**
- يدعم إضافة حساب واحد أو عدة حسابات دفعة واحدة
- يتجاهل الحسابات الموجودة مسبقاً (لا خطأ)
- يعرض ملخص: Added، Skipped، NotFound
- يسجل في `system_logs`

**مثال:**
```
أنت: /group_account_add vip acc1 acc2 acc3 nonexistent acc1
البوت: 📊 ملخص إضافة الحسابات إلى vip:
       
       ✅ تم الإضافة: 3
       ⏭️ تم التجاهل (موجود مسبقاً): 1
       ❌ غير موجود: 1
       
       الحسابات غير الموجودة:
       • nonexistent
```

---

### 7️⃣ `/group_account_del` (محسّن)

**الصيغة:**
```
/group_account_del <group> <acc1> <acc2> <acc3> ...
```

**السلوك:**
- يدعم حذف حساب واحد أو عدة حسابات دفعة واحدة
- يعرض ملخص: Removed، NotFound
- يسجل في `system_logs`

**مثال:**
```
أنت: /group_account_del vip acc1 acc2 nonexistent
البوت: 📊 ملخص حذف الحسابات من vip:
       
       ✅ تم الحذف: 2
       ❌ غير موجود: 1
       
       الحسابات غير الموجودة:
       • nonexistent
```

---

### 8️⃣ `/voucher_who_used`

**الصيغة:**
```
/voucher_who_used <code>
```

**السلوك:**
- يعرض معلومات القسيمة (نوع، قيمة، استخدامات)
- يعرض تاريخ كامل: أي بوت استخدمها + التاريخ والوقت
- يرتب حسب التاريخ (الأحدث أولاً)

**مثال:**
```
أنت: /voucher_who_used ABC123
البوت: 🎫 تقرير القسيمة: ABC123
       
       📋 النوع: users
       💰 القيمة: 100
       🎯 الهدف: الكل
       🔢 الاستخدامات: 3 / 5
       
       📊 سجل الاستخدام (3):
       
       🤖 mybot
       📅 2025-10-24 15:30:45
       
       🤖 testbot
       📅 2025-10-24 14:20:30
       
       🤖 mainbot
       📅 2025-10-24 12:10:15
```

**SQL المستخدم:**
```sql
SELECT vu.used_at, COALESCE(sb.label, '-') AS bot_label
FROM voucher_usage vu
LEFT JOIN sub_bots sb ON sb.id=vu.bot_id
WHERE vu.voucher_code=?
ORDER BY vu.used_at DESC;
```

---

## 📊 الأولويات والقيود

### قفل المجموعة (Lock)

| العملية | مقفلة (locked=1) | مفتوحة (locked=0) |
|---------|-----------------|------------------|
| `/group_rename` | ❌ ممنوع | ✅ مسموح |
| `/group_delete` | ❌ ممنوع | ✅ مسموح |
| `/group_bind` | ✅ مسموح | ✅ مسموح |
| `/group_unbind` | ✅ مسموح | ✅ مسموح |
| `/group_account_add` | ✅ مسموح | ✅ مسموح |
| `/group_account_del` | ✅ مسموح | ✅ مسموح |
| `/group_toggle` | ✅ مسموح | ✅ مسموح |

### قواعد التسمية

- **الأحرف المسموحة:** `[a-z0-9_.-]`
- **الطول الأقصى:** 32 حرف
- **التفرد:** case-insensitive (`vip` = `VIP`)
- **Regex:** `/^[a-z0-9_.-]{1,32}\$/i`

### قواعد الحذف

| الشرط | السماح بالحذف |
|-------|--------------|
| `locked=1` | ❌ لا |
| `is_default=1` | ❌ لا |
| مرتبطة ببوتات | ❌ لا (يطلب فك الربط أولاً) |
| لا تحقق أي شرط أعلاه | ✅ نعم |

---

## 🔄 Migration & Rollback

### تطبيق Migration

```bash
mysql -u user -p database < MIGRATION_GROUPS_VOUCHERS.sql
```

**الخصائص:**
- ✅ Idempotent (آمن للتشغيل مرتين)
- ✅ يفحص وجود الأعمدة قبل الإضافة
- ✅ ينقل بيانات `voucher_redemptions` إلى `voucher_usage`
- ✅ لا يحذف أي بيانات موجودة

### Rollback (إذا لزم)

```sql
-- إزالة عمود locked
ALTER TABLE account_groups DROP COLUMN locked;

-- إزالة الفهرس
DROP INDEX idx_unique_group_name_lower ON account_groups;

-- حذف جدول voucher_usage
DROP TABLE voucher_usage;
```

⚠️ **تحذير:** Rollback سيفقد بيانات تتبع القسائم!

---

## 📝 System Logs

جميع الأوامر الحساسة تُسجل في `system_logs`:

| الأمر | `action` | `details` |
|-------|-----------|------------|
| `/group_rename` | `group_rename` | `old → new` |
| `/group_delete` | `group_delete` | `group_name` |
| `/group_account_add` | `group_account_add_batch` | `Group: X, Added: N, Skipped: M` |
| `/group_account_del` | `group_account_del_batch` | `Group: X, Removed: N` |

**الاستعلام:**
```sql
SELECT * FROM system_logs 
WHERE action LIKE 'group_%' 
ORDER BY created_at DESC 
LIMIT 50;
```

---

## 🧪 Testing Checklist

### الاختبارات المطلوبة:

- [ ] **Test 1:** Lock → try rename/delete → should fail
- [ ] **Test 2:** Unlock → rename/delete → should succeed
- [ ] **Test 3:** Add 5 accounts batch → check summary
- [ ] **Test 4:** Delete 3 accounts batch → check summary
- [ ] **Test 5:** `/group_usage` shows correct counts
- [ ] **Test 6:** `/bot_groups` shows UNION of accounts
- [ ] **Test 7:** `/voucher_who_used` shows usage history
- [ ] **Test 8:** Run migration twice → no errors
- [ ] **Test 9:** Case-insensitive uniqueness (`vip` = `VIP`)
- [ ] **Test 10:** Delete group with bot links → should block

**ملف الاختبارات:** `TESTS_GROUPS_VOUCHERS.sql`

---

## 📁 الملفات المُعدّلة/المُنشأة

| الملف | التعديل | الحالة |
|-------|---------|--------|
| `control_bot.php` | +400 سطر (7 أوامر جديدة) | ✅ مُعدّل |
| `lib/help_content.php` | تحديث قسم المجموعات والقسائم | ✅ مُعدّل |
| `MIGRATION_GROUPS_VOUCHERS.sql` | Migration script | ✅ جديد |
| `TESTS_GROUPS_VOUCHERS.sql` | Test suite | ✅ جديد |
| `GROUPS_VOUCHERS_REPORT.md` | هذا التقرير | ✅ جديد |

---

## 🚀 خطوات النشر

### 1. تطبيق Migration

```bash
cd /path/to/project
mysql -u user -p database < MIGRATION_GROUPS_VOUCHERS.sql
```

### 2. رفع ملفات PHP

```bash
# رفع الملفات المُحدّثة
scp control_bot.php user@server:/var/www/project/
scp lib/help_content.php user@server:/var/www/project/lib/
```

### 3. التحقق

```bash
# في Telegram Bot
/help groups  ← يجب أن يعرض الأوامر الجديدة
/group_lock default  ← اختبار سريع
```

### 4. الاختبار الشامل

```bash
# تشغيل جميع الاختبارات
mysql -u user -p database < TESTS_GROUPS_VOUCHERS.sql
```

---

## 💡 الفوائد

| الميزة | قبل | بعد |
|--------|-----|-----|
| **حماية المجموعات** | ❌ لا توجد | ✅ Lock/Unlock |
| **إدارة الحسابات** | ➕ واحد تلو الآخر | ✅ دفعات |
| **استعلامات** | ❌ محدودة | ✅ usage + bot_groups |
| **تتبع القسائم** | ❌ لا يوجد | ✅ voucher_who_used |
| **تسمية المجموعات** | ❌ غير مدعوم | ✅ rename |
| **حذف آمن** | ⚠️ مباشر | ✅ with checks + confirm |

---

## 📊 الإحصائيات

- **أوامر جديدة:** 7
- **أوامر محسّنة:** 2
- **أسطر كود:** ~500
- **جداول جديدة:** 1
- **أعمدة جديدة:** 1
- **فهارس جديدة:** 1

---

## ✅ الخلاصة

النظام الآن يوفر:
- 🔒 **حماية متقدمة** للمجموعات الحساسة
- 📊 **إحصائيات شاملة** للاستخدام
- ⚡ **عمليات دفعية** للكفاءة
- 📈 **تتبع كامل** لاستخدام القسائم
- 🛡️ **أمان محسّن** مع التحققات والتسجيل

**جاهز للإنتاج!** ✅

---
**End of Report**
