# دليل نظام المقترحات — Suggestions System Guide

---

## نظرة عامة

نظام يُمكِّن المستخدمين من إرسال اقتراحاتهم، مشاكلهم، وأفكارهم.  
SuggestionsAgent يُحلِّل ويُقيِّم — الإدارة تتخذ القرار.

---

## أنواع الاقتراحات

| النوع | الوصف | أولوية Agent |
|-------|-------|-------------|
| `improvement` | اقتراح تحسين | 0.70 |
| `bug` | مشكلة تقنية | 0.90 (أعلى) |
| `solution` | حل مقترح | 0.65 |
| `new_service` | خدمة جديدة | 0.50 |
| `positive` | تقييم إيجابي | 0.20 |

---

## SuggestionsAgent::analyze()

### حساب الأولوية
```
score = (type_weight × 0.40) +
        (simplicity  × 0.25) +
        (novelty     × 0.20) +
        (votes       × 0.15)
score × plan_multiplier (pro=1.2, plus=1.1)

Labels:
  ≥ 0.80 → urgent
  ≥ 0.60 → high
  ≥ 0.40 → medium
  ≥ 0.20 → low
```

### Jaccard Duplicate Detection
```python
words_A = set(tokenize(new_suggestion))
words_B = set(tokenize(existing_suggestion))
similarity = |A ∩ B| / |A ∪ B|
# > 0.35 → potential duplicate
```

---

## Rate Limits

| الخطة | اقتراحات/يوم |
|-------|------------|
| Free | 2 |
| Plus | 5 |
| Pro | غير محدود |

---

## Gamification

```
إرسال اقتراح:     +10 نقطة
قبول اقتراح:      +50 نقطة
تنفيذ اقتراح:     +200 نقطة
badge: "صانع الأفكار" عند القبول
```

---

## التحويل التلقائي

```
type=bug → auto-create support_ticket (priority=high)
status=implemented → notify user + award 200 points
type=positive → للتسويق (testimonials)
votes > 50 → تنبيه إدارة
```

---

## API Reference

```
POST /api/suggestions/create.php  { type, title, description, service }
GET  /api/suggestions/list.php    ?sort=votes&type=improvement&limit=20
POST /api/suggestions/vote.php    { suggestion_id }
```

---

## Admin Workflow

```
admin.php → tab=suggestions:
  → عرض حسب الأولوية (urgent أولاً)
  → تحليل Agent لكل اقتراح
  → إجراء: قبول / تنفيذ / backlog / رفض
  → رد على المستخدم (اختياري)
  → تسجيل في audit_logs
```

---

## DB Schema

```sql
user_suggestions (30 حقل):
  type, service, title, description
  priority_score, priority_label, ai_summary
  affected_estimate, effort_level, effort_hours
  team_responsible, risk_level, roadmap_quarter
  status, admin_reply, votes_count

suggestion_votes:
  suggestion_id, user_id
  UNIQUE (suggestion_id, user_id)
```
