# Habit Recovery Controller

نظام أساسي (Core Controller) بسيط لإدارة حملات الإقلاع عن العادات السيئة:
لوحة ويب بسيطة + بوت تيليجرام + API داخلي يمكن لأي نظام فرعي آخر الاتصال به.

**بدون Docker. بدون PostgreSQL. بدون تعقيدات أمنية متقدمة.** فقط PHP + MySQL.

---

## 1. هيكل المشروع

```
habit-recovery-controller/
├── config/
│   └── config.php          # كل الإعدادات (DB، توكن تيليجرام، مسارات)
├── database/
│   └── schema.sql           # قاعدة البيانات كاملة
├── includes/
│   ├── db.php                # اتصال PDO
│   ├── telegram.php          # دوال إرسال تيليجرام (نص/صوت)
│   └── functions.php         # كل المنطق الأساسي (الحالة، الرسائل، الصوتيات، TTS)
├── api/
│   ├── status.php             # GET  - حالة الحملة الحالية
│   ├── start.php               # POST - تشغيل الحملة
│   ├── stop.php                 # POST - إيقاف الحملة
│   ├── emergency.php             # POST - تفعيل وضع الطوارئ
│   ├── messages.php               # GET/POST - إدارة الرسائل النصية
│   └── audio.php                   # GET/POST - إدارة الرسائل الصوتية
├── bot/
│   ├── webhook.php          # يستقبل تحديثات تيليجرام (/on /off /status /help /emergency)
│   └── set_webhook.php      # أداة سطر أوامر لضبط الـ Webhook
├── cron/
│   ├── notifier.php                       # عامل الإشعارات الدوري (يعمل باستمرار)
│   └── habit-notifier.service.example     # مثال خدمة systemd لتشغيله تلقائياً
├── public/                  # هذا هو ما يراه المستخدم في المتصفح
│   ├── index.php             # لوحة التحكم
│   ├── css/style.css
│   ├── js/app.js
│   └── uploads/audio/        # الملفات الصوتية المرفوعة/المولّدة تُحفظ هنا
└── logs/                     # (اختياري) لتوجيه سجل عامل الإشعارات إليه
```

---

## 2. المتطلبات

- PHP 8.0 أو أحدث، مع تفعيل امتدادي `pdo_mysql` و `curl`.
- MySQL 5.7+ أو MariaDB.
- صلاحية تنفيذ سكربتات CLI (لتشغيل عامل الإشعارات).
- دومين حقيقي يدعم **HTTPS** فقط إذا أردت تفعيل بوت تيليجرام (شرط من تيليجرام نفسه للـ Webhook). أثناء التطوير المحلي يمكنك تجاهل البوت وتجربة اللوحة والـ API فقط.

---

## 3. خطوات التشغيل

### الخطوة 1 — إنشاء قاعدة البيانات

```bash
mysql -u root -p < database/schema.sql
```

هذا سينشئ قاعدة `habit_recovery` وكل الجداول، مع بضع رسائل تجريبية. كما ينشئ تلقائياً مستخدم قاعدة بيانات مخصصاً باسم `habit_app` بكلمة مرور افتراضية `HabitApp@2026` ويمنحه صلاحيات كاملة على قاعدة `habit_recovery` فقط (أفضل أمنياً من استخدام `root` مباشرة في التطبيق، ويعمل بشكل صحيح بغض النظر عن طريقة مصادقة `root` في خادمك).

> ⚠️ **مهم:** قبل استخدام النظام في بيئة حقيقية (إنتاج)، غيّر كلمة المرور `HabitApp@2026` في كل من `database/schema.sql` (قبل التنفيذ) و `config/config.php` إلى كلمة مرور قوية خاصة بك.

### الخطوة 2 — تعديل الإعدادات

افتح `config/config.php` وتأكد أن بيانات قاعدة البيانات تطابق ما تم إنشاؤه في الخطوة السابقة:

```php
define('DB_HOST', '127.0.0.1');
define('DB_NAME', 'habit_recovery');
define('DB_USER', 'habit_app');
define('DB_PASS', 'HabitApp@2026'); // غيّرها لتطابق كلمة المرور التي اخترتها في schema.sql

define('TELEGRAM_BOT_TOKEN', 'التوكن_من_BotFather');
define('TELEGRAM_CHAT_ID', 'آيدي_المحادثة');
```

**كيف تحصل على التوكن وآيدي المحادثة:**
1. تحدث مع [@BotFather](https://t.me/BotFather) على تيليجرام وأنشئ بوتاً جديداً بأمر `/newbot`، سيعطيك توكناً.
2. أرسل أي رسالة لبوتك الجديد (مثلاً "هلا").
3. افتح في المتصفح: `https://api.telegram.org/bot<التوكن>/getUpdates`
4. ستجد `chat.id` في الرد — هذا هو `TELEGRAM_CHAT_ID`.

### الخطوة 3 — تشغيل السيرفر

للتجربة السريعة محلياً (بدون Apache)، شغّل من **جذر المشروع** (المجلد الذي يحتوي على `public/` و `api/` و `bot/` معاً):

```bash
php -S localhost:8000
```

ثم افتح المتصفح على:

```
http://localhost:8000/public/index.php
```

> ملاحظة مهمة: لاحظ أن جذر الخادم (Document Root) هو **مجلد المشروع نفسه**، وليس مجلد `public/` فقط. هذا مقصود ليبقى التصميم بسيطاً بدون أي إعادة كتابة مسارات (rewrite rules)، حيث تحتاج اللوحة الوصول لمجلدي `api/` المجاور لها مباشرة بمسار نسبي `../api/`.

لتشغيله عبر Apache: اجعل `DocumentRoot` يشير إلى مجلد المشروع الرئيسي بنفس الطريقة، وفعّل `mod_rewrite` ليس ضرورياً هنا لأن لا توجد أي قواعد إعادة كتابة.

### الخطوة 4 — تشغيل عامل الإشعارات (Notifier Daemon)

هذا السكربت هو الذي يرسل الرسائل التحفيزية الدورية وتنبيهات الطوارئ تلقائياً. يجب أن يبقى يعمل بشكل دائم في الخلفية:

**للتجربة السريعة:**
```bash
nohup php cron/notifier.php > logs/notifier.log 2>&1 &
```

**للتشغيل الدائم على سيرفر إنتاج (موصى به):** استخدم `systemd`
```bash
sudo cp cron/habit-notifier.service.example /etc/systemd/system/habit-notifier.service
# عدّل المسارات داخل الملف أولاً (WorkingDirectory و ExecStart)
sudo systemctl daemon-reload
sudo systemctl enable habit-notifier
sudo systemctl start habit-notifier
```

> لماذا سكربت مستمر بدل crontab عادي؟ لأن وضع الطوارئ يحتاج فواصل زمنية قصيرة (مثلاً كل 30 ثانية)، وهذا غير ممكن بدقة عبر crontab التقليدي الذي لا يعمل بدقة أقل من دقيقة.

### الخطوة 5 — ربط بوت تيليجرام (Webhook)

بعد رفع المشروع على سيرفر حقيقي بدومين HTTPS:

```bash
php bot/set_webhook.php https://your-domain.com/bot/webhook.php
```

أو مباشرة عبر المتصفح:
```
https://api.telegram.org/bot<التوكن>/setWebhook?url=https://your-domain.com/bot/webhook.php
```

جرّب الآن إرسال `/help` للبوت.

---

## 4. واجهة API الداخلية

كل المسارات نسبية لجذر المشروع (مثال: `http://your-domain.com/api/status.php`)

| Method | Endpoint            | الوصف                                                   |
|--------|----------------------|----------------------------------------------------------|
| GET    | `/api/status.php`    | حالة الحملة الحالية + آخر إشعار                           |
| POST   | `/api/start.php`     | تشغيل الحملة                                              |
| POST   | `/api/stop.php`      | إيقاف الحملة                                              |
| POST   | `/api/emergency.php` | تفعيل وضع الطوارئ (إرسال فوري + تنبيهات متقاربة)            |
| GET    | `/api/messages.php`  | جلب كل الرسائل النصية                                     |
| POST   | `/api/messages.php`  | إضافة/تعديل/حذف رسالة — `{"action":"add|update|delete", ...}` |
| GET    | `/api/audio.php`     | جلب كل الملفات الصوتية                                    |
| POST   | `/api/audio.php`     | إضافة عبر TTS أو رفع mp3، أو حذف — `multipart/form-data`   |

كل الردود JSON. هذا يعني أن أي نظام فرعي مستقبلي (تطبيق موبايل، إضافة متصفح، سكربت بايثون...) يمكنه التحكم بالحملة بمجرد إرسال طلبات HTTP لهذه المسارات، دون الحاجة لمعرفة أي تفاصيل داخلية عن قاعدة البيانات أو تيليجرام.

---

## 5. كيف تعمل الإشعارات والصوت داخل الصفحة

- **تيليجرام:** يرسلها `cron/notifier.php` تلقائياً وفق الفاصل الزمني المحدد في جدول `settings` (`normal_interval_minutes` للوضع العادي، `emergency_interval_seconds` لوضع الطوارئ).
- **إشعارات المتصفح:** زر "تفعيل إشعارات المتصفح" في اللوحة يطلب صلاحية `Notification` من المتصفح. بعد ذلك، تستطلع الصفحة `/api/status.php` كل 5 ثوانٍ، وعند وجود إشعار جديد تعرض Notification وتُشغّل نغمة تنبيه قصيرة (مولّدة برمجياً بدون أي ملف صوتي خارجي عبر Web Audio API).
- **وضع الطوارئ:** يظهر شريط أحمر نابض في أعلى اللوحة طوال فترة التفعيل، بالإضافة إلى تنبيهات تيليجرام متقاربة.

---

## 6. تعديل الفواصل الزمنية

عبر MySQL مباشرة (لا توجد واجهة لذلك في اللوحة حالياً لتبسيط المشروع):

```sql
UPDATE settings SET value = '30' WHERE `key` = 'normal_interval_minutes'; -- بالدقائق
UPDATE settings SET value = '15' WHERE `key` = 'emergency_interval_seconds'; -- بالثواني
```

---

## 7. ملاحظة حول تحويل النص إلى صوت (TTS)

النظام يستخدم خدمة Google Translate TTS غير الرسمية (مجانية، بدون مفتاح API) — مناسبة للتطوير والتجربة. إذا احتجت موثوقية أعلى لاستخدام إنتاجي حقيقي، عدّل فقط دالة `generateTTS()` في `includes/functions.php` لتستخدم خدمة رسمية (Google Cloud TTS، Azure Speech، ElevenLabs...) مع الحفاظ على نفس التوقيع: تدخل نص، يخرج رابط ملف mp3.

---

## 8. التوسعة المستقبلية

البنية مصممة لتكون مركزاً (Core) تُربط به أنظمة فرعية إضافية بسهولة:

- أي نظام جديد فقط يستدعي `api/*.php` بطلبات HTTP عادية.
- لإضافة قناة إشعار جديدة (مثل واتساب أو بريد إلكتروني)، أضف دالة جديدة في `includes/functions.php` (مثلاً `sendWhatsappAlert()`) واستدعها من `sendCampaignAlert()`.
- لإضافة أمر بوت جديد، أضف حالة `case` جديدة في `bot/webhook.php`.
- لإضافة جدول/ميزة جديدة، أضف الجدول في `database/schema.sql` ودوالها في `includes/functions.php`، ثم endpoint جديد في `api/`.

بالتوفيق في رحلتك! 💪