# واجهات API العامة (Public API)

ملخص لملفات مجلد `api/public` التي يصل إليها **المستخدمون المسجلون والغير مسجلين** — ما يُعرض للجميع وما له خصوصيات.

---

## 1) هيكل الملفات والغرض

| الملف | الطريقة | الغرض | يتطلب تسجيل؟ |
|-------|---------|--------|---------------|
| `index.php` | GET | نقطة دخول/توجيه (موبايل، محركات بحث، إلخ) | لا |
| `session_config.php` | - | ثوابت الجلسة فقط (لا endpoint) | - |
| `get_properties.php` | GET | قائمة عقارات (مكتمل، toggle=1) | لا |
| `get_property_details.php` | GET | تفاصيل عقار واحد بـ `?id=` | لا |
| `property_details.php` | GET | صفحة تفاصيل عقار (ويب، قد تستخدم للعرض) | لا (مع تمييز مالك) |
| `get_similar_properties.php` | POST | عقارات مشابهة لعقار معيّن | لا |
| `get_map_properties.php` | GET | **عقارات الخريطة** (مكتمل + toggle=1 + إحداثيات صالحة) — لتبويب الخريطة في التطبيق | لا |
| `get_locations.php` | GET | مناطق/مدن/أحياء (من جدول regions) | لا |
| `get_stats.php` | GET | إحصائيات (يعتمد db-connect-local) | لا |
| `get_statistics.php` | GET | إحصائيات مبسطة (قيم ثابتة) | لا |
| `get_messages.php` | GET / POST / PUT | **الرسائل والمحادثات** (انظر القسم 2) | **خصوصيات — انظر أدناه** |
| `toggle_favorite.php` | POST | إضافة/إزالة من المفضلة | **نعم (جلسة)** |
| `rate_property.php` | POST | تقييم عقار | **نعم (جلسة)** |
| `profile_user.php` | GET | صفحة ملف مستخدم (نوع: مستخدم) | لا |
| `profile_office.php` | GET | صفحة ملف مكتب/مؤجر/مالك | لا |
| `map.php` | GET | خريطة عقارات (ويب، مع action للـ AJAX) | لا |
| `property_map.php` | - | مرتبط بالخريطة | لا |

---

## 2) الرسائل — `get_messages.php` (الخصوصيات المهمة)

الملف يعمل بثلاث حالات حسب المعاملات:

### 2.1 طلب GET

- **`user_id` + `conversation_with`**  
  - يُرجع رسائل المحادثة بين المستخدمين فقط.  
  - **الخصوصية:** أي شخص يعرف `user_id` و `conversation_with` يمكنه طلب هذه المحادثة. **لا يوجد تحقق من الجلسة أو من أن الطالب هو أحد الطرفين.** يُفضّل ربط الطلب بالجلسة (مثلاً أن يكون `user_id` = المستخدم الحالي فقط).

- **`user_id` فقط**  
  - يُرجع قائمة المحادثات الأخيرة لذلك المستخدم (آخر رسالة، عدد غير المقروء، إلخ).  
  - **نفس الملاحظة:** من يعرف `user_id` يرى قائمة محادثاته دون تحقق تسجيل دخول.

- **بدون `user_id` (ولا `conversation_with`)**  
  - يُرجع **آخر 20 رسالة من جدول الرسائل كاملاً** (جميع المستخدمين).  
  - **مخاطرة خصوصية عالية:** وصول غير مسموح لرسائل خاصة. يُفضّل إزالة هذا المسار أو تقييده بصلاحيات إدارية فقط.

### 2.2 طلب POST (إرسال رسالة)

- يُدخل رسالة جديدة بناءً على `sender_id`, `receiver_id`, ونص/وسائط.
- **لا يوجد تحقق من الجلسة:** أي شخص يمكنه إرسال رسالة باسم أي `sender_id` (انتحال هوية). يجب ربط `sender_id` بالمستخدم المسجل من الجلسة.

### 2.3 طلب PUT (تحديث حالة القراءة)

- يحدّث `is_read` لرسائل من محادثة معيّنة (`user_id`, `conversation_with`).
- **نفس الفكرة:** يجب التأكد أن `user_id` هو المستخدم الحالي من الجلسة.

### خلاصة الرسائل

- الملف **عام** من ناحية المسار (تحت `public`) لكن **المحتوى خاص بالمستخدمين**.
- يُنصح بـ:  
  - إما نقل منطق الرسائل إلى API يتطلب تسجيل دخول والتحقق من الجلسة،  
  - أو الإبقاء على الملف في public لكن **التحقق في بداية الطلب** أن الهوية (مثلاً `user_id`) تطابق المستخدم المسجل، و**منع** الطلب الذي لا يحوي `user_id` أو يعيد "آخر 20 رسالة عالمية".

---

## 3) نقاط أخرى مهمة

### 3.1 المفضلة والتقييم

- **`toggle_favorite.php`**: يتحقق من `$_SESSION['usercode']` — للمسجلين فقط، سليم.
- **`rate_property.php`**: يتحقق من `$_SESSION['usercode']` — للمسجلين فقط، سليم.

### 3.2 الاتصال بقاعدة البيانات

- أغلب الملفات تستخدم `includes/db-connect-test.php` (أو ما يُعرَف فيه كـ `$pdo` / `$connect`).
- `get_stats.php` يستخدم `db-connect-local.php` و`$conn` — قد تحتاج توحيد مع بقية المشروع.

### 3.3 التوجيه والويب

- **`index.php`**: ثقيل (توجيه أجهزة، محركات بحث، دومينات). يوجّه الموبايل إلى `/mobile/web/` ومحركات البحث إلى Flutter.
- **`profile_user.php`**: إذا كان المستخدم من نوع مكتب/مالك/مؤجر يتم إعادة التوجيه إلى `profile_office.php?usercode=...`.
- **`property_details.php`**: يفرق بين زائر عادي ومالك العقار (`$isOwner`) لعرض عناصر إضافية أو روابط تحرير.

### 3.4 CORS والرؤوس

- معظم الملفات تضبط `Access-Control-Allow-Origin` (غالباً `*`) و`Content-Type: application/json` وطرق GET/POST/PUT حسب الحاجة.

---

## 4) توصيات سريعة

1. **الرسائل:** إما تحقق جلسة صارم لـ `get_messages.php` وربط `user_id` بالمستخدم الحالي فقط، أو نقله إلى مسار API محمي؛ وإلغاء أو تأمين مسار "آخر 20 رسالة عامة".
2. **توحيد DB:** مراجعة استخدام `db-connect-local` في `get_stats.php` مع بقية الـ API.
3. **أسماء المعاملات:** واجهة الويب تستخدم أحياناً `with=` للمحادثة؛ الـ API يتوقع `user_id` و`conversation_with`. مراجعة التوافق بين الواجهة والـ API.

---

تم إعداد هذا الملخص بناءً على قراءة ملفات مجلد `api/public` وتحديد الخصوصيات (خاصة نظام الرسائل).
