# سجل الأخطاء وتتبع المشاكل (Error Log & Bug Tracker)

يحتوي هذا الملف على تصنيف شامل لجميع الأخطاء البرمجية والمنطقية المحتملة أو التي تم اكتشافها في **SteganoPixel**، مع توفير السبب الجذري والحلول الفورية للمطورين.

---

## 1. جدول الأخطاء الشامل (Bugs Index)

| كود الخطأ | الوصف | السبب الجذري (Root Cause) | الملف / اللغة | الحل المقترح | الخطورة |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **`ERR-STG-01`** | `النص أطول من السعة المتاحة داخل هذه الصورة.` | محاولة تضمين نص يتجاوز حجمه (بالبايت) عدد البتات المتاحة في القنوات اللونية (RGB) للصورة المرفوعة. | `steganography.ts` (Logic) | استخدام صورة ذات أبعاد أكبر (عرض × طول) أو تقليل طول النص المراد تضمينه. | **High** |
| **`ERR-STG-02`** | `أبعاد الصورة صغيرة جدًا ولا تحتوي على مساحة كافية.` | الصورة المرفوعة أصغر من أن تستوعب حتى التوقيع السحري (7 بايت) ورأس الطول (4 بايت). | `steganography.ts` (Logic) | فرض حد أدنى لأبعاد الصور المرفوعة (مثلاً 10×10 بكسل على الأقل). | **Medium** |
| **`ERR-STG-03`** | `لم يتم العثور على نص مخفي داخل هذه الصورة.` | عدم تطابق البايتات السبعة الأولى المستخرجة من الصورة مع التوقيع السحري `TXTIMG1`. | `steganography.ts` (Logic) | التأكد من أن الصورة المرفوعة تم تشفيرها مسبقاً باستخدام هذا التطبيق ولم تتعرض للضغط. | **Low** |
| **`ERR-STG-04`** | `البيانات المخفية داخل الصورة تبدو تالفة.` | طول الرسالة المقروء من الرأس يشير إلى حجم يلتهم مساحة تتجاوز الأبعاد الفعلية للصورة. | `steganography.ts` (Logic) | إبلاغ المستخدم بأن الصورة تعرضت لتعديل أو تلف أو تم قصها (Cropping). | **Medium** |
| **`ERR-UI-01`** | `عدم تنزيل الصورة عند الضغط على زر التنزيل.` | الاعتماد على وسم `<a>` مباشر مع رابط `Blob` داخل React، ما يمنع بعض المتصفحات من إطلاق التنزيل. | `App.tsx` (UI/UX) | إطلاق التنزيل برمجياً عبر حقن وسم `<a>` مؤقت في الـ DOM، النقر عليه، ثم حذفه. | **Critical** |
| **`ERR-UI-02`** | `فشل النسخ التلقائي للنص المستخرج إلى الحافظة.` | تقييد أمني من المتصفح (Clipboard API Protocol) يمنع النسخ إذا لم يتم عبر نقرة مباشرة، أو عدم استخدام `HTTPS`. | `App.tsx` (UI/UX) | توفير مربع نص مقروء (`<textarea>`) ليتمكن المستخدم من النسخ اليدوي، مع إظهار رسالة تنبيه. | **Low** |
| **`ERR-PERF-01`** | `تجميد المتصفح أثناء تشفير صورة عملاقة (4K+).` | تنفيذ حلقات المعالجة التكرارية لمليارات البتات على الخيط الرئيسي (Main UI Thread). | `steganography.ts` (Performance) | نقل دوال المعالجة (`embed` / `extract`) إلى خيط عمل خلفي (Web Worker) أو تقسيم المعالجة. | **High** |
| **`ERR-COMP-01`** | `تلف البيانات المخفية عند إرسال الصورة عبر الواتساب.` | قيام منصات التواصل الاجتماعي بإعادة ضغط الصور (Lossy JPG/WEBP Compression) ومحو البتات الدقيقة. | البيئة الخارجية (Compatibility) | توعية المستخدم بإرسال الصورة كـ «ملف / مستند» (File/Document) للحفاظ على بنيتها الخام. | **Critical** |
| **`ERR-SYN-01`** | `Property 'onDownload' is missing in type...` | عدم تمرير خاصية إجبارية معرّفة في واجهة TypeScript إلى المكون الفعلي عند استدعائه. | `App.tsx` (Syntax) | مراجعة تعريف واجهة `DownloadCard` وتمرير دالة `onDownload` في جميع الاستدعاءات. | **Critical** |

---

## 2. تصنيف الأخطاء حسب النوع (Categorized Diagnostics)

### أ. أخطاء بنيوية (Syntax Errors)
تحدث هذه الأخطاء أثناء مرحلة الكتابة والتجميع (Compilation). يمنع مترجم TypeScript تشغيل التطبيق إذا اكتشف عدم تطابق في الأنواع أو نسيان تمرير معاملات إجبارية (مثل `ERR-SYN-01`).
* **طريقة الوقاية:** الاعتماد الدائم على إضافات التحقق البرمجي (ESLint) وتركيب بيئة TypeScript صارمة (`"strict": true` في `tsconfig.json`).

### ب. أخطاء منطقية (Logic Errors)
تتركز في محرك الإخفاء الرقمي (`steganography.ts`). تتضمن حسابات إزاحة البتات (`Bitwise Shifts`) أو قراءة رؤوس غير متوافقة (مثل `ERR-STG-01` و `ERR-STG-03`).
* **طريقة الوقاية:** كتابة اختبارات وحدة (Unit Tests) للتحقق من أن نصاً معيناً يتم تضمينه ثم استخراجه بوضعية مطابقة 100% (`assert(extracted === original)`).

### جـ. أخطاء الأداء (Performance Errors)
تظهر عند التعامل مع صور ضخمة جداً (`4000×4000` بكسل فما فوق). مصفوفة `ImageData` لمثل هذه الصور تحتوي على أكثر من 64 مليون عنصر، والمرور عليها في الخيط الرئيسي يسبب تجميد الواجهة (`ERR-PERF-01`).
* **طريقة الوقاية:** إضافة شريط تقدم (Progress Bar) وتقسيم العمليات باستخدام `requestAnimationFrame` أو الاستعانة بـ `Web Workers`.

### د. أخطاء التوافق (Compatibility Errors)
تخرج عن سيطرة الكود المصدري وتتعلق بسلوك المتصفحات أو التطبيقات الخارجية. أشهرها قيام أنظمة التشغيل أو برامج المحادثة بتغيير صيغة الصورة من `PNG` إلى `JPG` (`ERR-COMP-01`).
* **طريقة الوقاية:** عرض إرشادات واضحة للمستخدمين ضمن الواجهة، وإجبار تصدير الصور بلاحقة `.png` صريحة.

### هـ. أخطاء الواجهة والتجربة (UI/UX Errors)
تؤثر على انسيابية العمل، مثل عدم استجابة زر التنزيل في متصفحات مدمجة داخل تطبيقات (In-App Browsers) أو فشل الصلاحيات الأمنية للنسخ (`ERR-UI-01` و `ERR-UI-02`).
* **طريقة الوقاية:** توفير بدائل يدوية دائماً (Fallback Mechanisms) مثل عرض الروابط المباشرة ومربعات النصوص القابلة للتحديد.