الملفات الأساسية
Signed-off-by: Mohamed-Abdelhalim2 <codepen.io.dropper985@passinbox.com>
هذا الالتزام موجود في:
122
.gitignore
مباع
Normal file
122
.gitignore
مباع
Normal file
@@ -0,0 +1,122 @@
|
||||
# Logs
|
||||
logs
|
||||
*.log
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
pnpm-debug.log*
|
||||
lerna-debug.log*
|
||||
|
||||
# Diagnostic reports (https://nodejs.org/api/report.html)
|
||||
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
|
||||
|
||||
# Runtime data
|
||||
pids
|
||||
*.pid
|
||||
*.seed
|
||||
*.pid.lock
|
||||
|
||||
# Directory for instrumented libs generated by jscoverage/JSCover
|
||||
lib-cov
|
||||
|
||||
# Coverage directory used by tools like istanbul
|
||||
coverage
|
||||
*.lcov
|
||||
|
||||
# nyc test coverage
|
||||
.nyc_output
|
||||
|
||||
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
|
||||
.grunt
|
||||
|
||||
# Bower dependency directory (https://bower.io/)
|
||||
bower_components
|
||||
|
||||
# node-waf configuration
|
||||
.lock-wscript
|
||||
|
||||
# Compiled binary addons (https://nodejs.org/api/addons.html)
|
||||
build/Release
|
||||
|
||||
# Dependency directories
|
||||
node_modules/
|
||||
jspm_packages/
|
||||
|
||||
# TypeScript v1 declaration files
|
||||
typings/
|
||||
|
||||
# Optional npm cache directory
|
||||
.npm
|
||||
|
||||
# Optional eslint cache
|
||||
.eslintcache
|
||||
|
||||
# Microbundle cache
|
||||
.rpt2_cache/
|
||||
.rts2_cache_cjs/
|
||||
.rts2_cache_es/
|
||||
.rts2_cache_umd/
|
||||
|
||||
# Optional REPL history
|
||||
.node_repl_history
|
||||
|
||||
# Output 'dist' directory
|
||||
dist
|
||||
dist-ssr
|
||||
|
||||
# Output 'build' directory (for generic builders)
|
||||
build
|
||||
|
||||
# Next.js build output
|
||||
.next
|
||||
|
||||
# Nuxt.js build output
|
||||
.nuxt
|
||||
|
||||
# Gatsby files
|
||||
.cache/
|
||||
# Comment in the public line in if your project uses Gatsby and *not* Next.js
|
||||
# public
|
||||
|
||||
# vuepress build output
|
||||
.vuepress/dist
|
||||
|
||||
# serverless directories
|
||||
.serverless/
|
||||
|
||||
# FuseBox cache
|
||||
.fusebox/
|
||||
|
||||
# DynamoDB Local files
|
||||
.dynamodb/
|
||||
|
||||
# TernJS port file
|
||||
.tern-port
|
||||
|
||||
# Mac OS X
|
||||
.DS_Store
|
||||
*.DS_Store
|
||||
.AppleDouble
|
||||
.LSOverride
|
||||
Icon
|
||||
|
||||
# Windows
|
||||
Thumbs.db
|
||||
Thumbs.db:encryptable
|
||||
ehthumbs.db
|
||||
ehthumbs_vista.db
|
||||
*.stackdump
|
||||
Desktop.ini
|
||||
$RECYCLE.BIN/
|
||||
|
||||
# JetBrains / IntelliJ IDEs
|
||||
.idea/
|
||||
*.iml
|
||||
*.iws
|
||||
|
||||
# VS Code IDE
|
||||
.vscode/*
|
||||
!.vscode/settings.json
|
||||
!.vscode/tasks.json
|
||||
!.vscode/launch.json
|
||||
!.vscode/extensions.json
|
||||
109
CUSTOMIZATION_GUIDE.md
Normal file
109
CUSTOMIZATION_GUIDE.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# دليل التخصيص وإدارة الإضافات (Customization & Asset Guide)
|
||||
|
||||
يوفر هذا الدليل شرحاً تفصيلياً لجميع الإضافات (Assets)، الخطوط، الألوان، والمكتبات المستخدمة في **SteganoPixel**، مع تعليمات خطوة بخطوة للمطورين حول كيفية تعديلها أو استبدالها وتصحيح المشاكل المحتملة.
|
||||
|
||||
---
|
||||
|
||||
## 1. الإضافات المستخدمة (Assets Inventory)
|
||||
|
||||
### أ. الصور والأيقونات (Images & Icons)
|
||||
* **المسار الدقيق:** `public/` (للملفات الثابتة) وداخل كود `src/App.tsx` (أيقونات متجهات SVG المدمجة).
|
||||
* **الغرض منها:** تعزيز التجربة البصرية التفاعلية (أيقونات السحب والإفلات، علامات النجاح، ومؤشرات التنزيل).
|
||||
* **كيفية التعديل أو الاستبدال:**
|
||||
* لاستبدال أيقونات الواجهة، ابحث عن وسوم `<svg>` في `src/App.tsx` واستبدلها بأي كود SVG مفضل (مثلاً من *Lucide* أو *Heroicons*).
|
||||
* لإضافة شعار ثابت، ضع ملف الصورة (مثلاً `logo.png`) في مجلد `public/` واستدعه في الكود عبر `<img src="/logo.png" alt="Logo" />`.
|
||||
* **تصحيح المشاكل:**
|
||||
* **مشكلة:** الأيقونة تظهر بحجم ضخم أو مشوه.
|
||||
* **الحل:** تأكد من تحديد خصائص العرض والطول في أصناف Tailwind (مثلاً `h-6 w-6`)، وتأكد من وجود خاصية `fill="none"` و `stroke="currentColor"` في وسم الـ SVG الأساسي.
|
||||
|
||||
### ب. الخطوط (Fonts & Typography)
|
||||
* **المسار الدقيق:** معرّفة في `src/index.css` (`:root { font-family: ... }`) ويتم الاعتماد على الخطوط القياسية ومكتبة *Inter*.
|
||||
* **الغرض منها:** تأمين قراءة ممتازة ومريحة للنصوص والتعليمات باللغتين العربية والإنجليزية.
|
||||
* **كيفية تغيير الخطوط (عناوين، نصوص أساسية، أكواد):**
|
||||
1. افتح ملف `src/index.css`.
|
||||
2. لتغيير خط **العناوين والنصوص الأساسية**، قم باستيراد خطك المفضل من *Google Fonts* (مثلاً *Cairo* أو *Tajawal*) في رأس الملف:
|
||||
```css
|
||||
@import url('https://fonts.googleapis.com/css2?family=Tajawal:wght@400;700;900&display=swap');
|
||||
|
||||
:root {
|
||||
font-family: 'Tajawal', system-ui, -apple-system, sans-serif;
|
||||
}
|
||||
```
|
||||
3. لتخصيص خط **الأكواد والنصوص المستخرجة** (Monospace)، أضف تعريفاً خاصاً لعناصر `<textarea>`:
|
||||
```css
|
||||
textarea {
|
||||
font-family: 'Fira Code', 'Courier New', monospace;
|
||||
}
|
||||
```
|
||||
* **تصحيح المشاكل:**
|
||||
* **مشكلة:** الخط العربي يظهر متقطعاً أو أوزانه (Bold/Regular) لا تعمل بشكل صحيح.
|
||||
* **الحل:** تأكد من تضمين جميع الأوزان المطلوبة في رابط الاستيراد (`wght@400;600;800`)، وتأكد من عدم وجود أخطاء إملائية في اسم عائلة الخط داخل `:root`.
|
||||
|
||||
### جـ. الألوان والثيمات (Colors & Theming System)
|
||||
* **المسار الدقيق:** معرّفة كفئات ذريّة (Utility Classes) في `src/App.tsx` و كمتغيرات في `src/index.css`.
|
||||
* **الغرض منها:** تحديد الهوية البصرية للتطبيق (اللون البنفسجي، الخلفيات الزجاجية، والتنبيهات).
|
||||
* **كيفية تعديل الألوان والثيمات:**
|
||||
* **تغيير اللون الأساسي (Primary Theme):**
|
||||
التطبيق يستخدم حالياً فئات `violet-500` حتى `violet-700` و `indigo-600`. لتحويل ثيم التطبيق إلى **الأزرق الملكي (Blue Theme)** مثلاً، استبدل كل:
|
||||
* `from-violet-500 to-indigo-600` ➔ `from-blue-500 to-cyan-600`
|
||||
* `bg-violet-600` hover `hover:bg-violet-700` ➔ `bg-blue-600` hover `hover:bg-blue-700`
|
||||
* `text-violet-700` ➔ `text-blue-700`
|
||||
* **تعديل خلفية التدرج العامة:**
|
||||
افتح `src/App.tsx` وعدل حاوية الصفحة الجذرية:
|
||||
```tsx
|
||||
// من البنفسجي إلى الأبيض:
|
||||
bg-[radial-gradient(circle_at_top,_rgba(124,58,237,0.16),_transparent_34%),linear-gradient(180deg,_#f8fafc,_#eef2ff_45%,_#ffffff)]
|
||||
|
||||
// لتحويله إلى ثيم رمادي داكن (Dark Theme):
|
||||
bg-[radial-gradient(circle_at_top,_rgba(30,41,59,0.5),_transparent_34%),linear-gradient(180deg,_#0f172a,_#1e293b_45%,_#0f172a)] text-slate-100
|
||||
```
|
||||
* **تصحيح المشاكل:**
|
||||
* **مشكلة:** التدرج اللوني لا يظهر أو يظهر كخلفية بيضاء صلبة.
|
||||
* **الحل:** تأكد من عدم وجود مسافات فارغة غير مسموح بها داخل الأقواس المعقوفة في Tailwind `bg-[...]` (استخدم الشرطة السفلية `_` بدلاً من المسافة).
|
||||
|
||||
### د. المكتبات الخارجية (Third-Party Libraries)
|
||||
* **المكتبات المستخدمة:**
|
||||
1. `react` (v18.3.1): مكتبة الواجهات.
|
||||
2. `react-dom` (v18.3.1): مشغل React على المتصفح.
|
||||
3. `tailwindcss` (v4.0.0): إطار عمل الأنماط.
|
||||
* **المسار الدقيق:** `package.json`.
|
||||
* **كيفية التعديل أو التحديث:**
|
||||
لتحديث المكتبات إلى أحدث إصدار، نفذ الأمر التالي في موجه الأوامر:
|
||||
```bash
|
||||
npm update
|
||||
```
|
||||
أو لتثبيت مكتبة إضافية (مثلاً `canvas-confetti` للاحتفال عند نجاح الاستخراج):
|
||||
```bash
|
||||
npm install canvas-confetti
|
||||
npm install -D @types/canvas-confetti
|
||||
```
|
||||
* **تصحيح المشاكل:**
|
||||
* **مشكلة:** ظهور تعارض في الحزم بعد التحديث (Peer Dependencies Conflict).
|
||||
* **الحل:** احذف مجلد `node_modules` وملف `package-lock.json` ثم أعد التثبيت النظيف عبر `npm install`.
|
||||
|
||||
---
|
||||
|
||||
## 2. تخصيص المكونات التفاعلية (Components Customization)
|
||||
|
||||
### تخصيص بطاقة الرفع (`UploadCard`)
|
||||
إذا أردت تغيير السلوك ليقبل ملفات PDF أو نصوص، يمكنك تعديل خاصية `accept` داخل مكون `UploadCard` في `src/App.tsx`:
|
||||
```tsx
|
||||
// الوضع الحالي (صور فقط):
|
||||
<input id={inputId} type="file" accept="image/*" className="hidden" onChange={handleChange} />
|
||||
|
||||
// لتفعيل قبول الصور والوثائق:
|
||||
<input id={inputId} type="file" accept="image/*,.pdf,.docx" className="hidden" onChange={handleChange} />
|
||||
```
|
||||
|
||||
### تخصيص بطاقة التنزيل (`DownloadCard`)
|
||||
لتعديل اسم الملف الافتراضي عند التنزيل، ابحث عن استدعاء `setEncodedAsset` في دالة `handleEncode`:
|
||||
```tsx
|
||||
setEncodedAsset({
|
||||
url,
|
||||
// يمكنك تغيير اللاحقة "-hidden" إلى أي عبارة أخرى:
|
||||
fileName: `${baseName(encodeImage.file.name)}-secret-data.png`,
|
||||
size: blob.size,
|
||||
width: canvas.width,
|
||||
height: canvas.height,
|
||||
});
|
||||
```
|
||||
43
ERROR_LOG.md
Normal file
43
ERROR_LOG.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# سجل الأخطاء وتتبع المشاكل (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) مثل عرض الروابط المباشرة ومربعات النصوص القابلة للتحديد.
|
||||
185
GIT.md
Normal file
185
GIT.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# دليل إدارة المستودع وبروتوكولات العمل على GitHub (Git / GitHub Operations Guide)
|
||||
|
||||
يوفر هذا الملف إطار العمل الشامل والقياسي (Standard Operating Procedures) لإدارة مستودع **ستيجانو بكسل (SteganoPixel)** على منصة GitHub. يهدف هذا الدليل إلى توحيد جهود المطورين، تنظيم المساهمات البرمجية، وضمان أعلى مستويات الجودة والأمان خلال دورة حياة التطوير.
|
||||
|
||||
---
|
||||
|
||||
## 1. إعدادات المستودع الموصى بها على GitHub (Repository Configuration)
|
||||
|
||||
لضمان أمان الشفرة المصدرية وسلاسة العمل الجماعي، يُوصى بتطبيق الإعدادات التالية في لوحة تحكم المستودع (`Settings`):
|
||||
|
||||
### أ. البيانات الوصفية والهوية (Metadata & Topics)
|
||||
* **اسم المستودع:** `steganopixel`
|
||||
* **الوصف (Description):**
|
||||
> SteganoPixel 🎨 - Advanced Client-Side LSB Steganography Web Application in Arabic for Embedding, Extracting, and Sanitizing Hidden Texts in Digital Images.
|
||||
* **الوسوم (Topics / Tags):**
|
||||
`steganography`, `lsb-steganography`, `react`, `tailwind-css`, `typescript`, `vite`, `image-processing`, `security`, `privacy`, `arabic-web-app`
|
||||
* **الموقع الرسمي (Website):** رابط الاستضافة المباشر (مثل `https://steganopixel.vercel.app` أو `https://your-username.github.io/steganopixel`).
|
||||
|
||||
### ب. قواعد حماية الفروع (Branch Protection Rules)
|
||||
يجب تفعيل حماية صارمة على الفرعين المحوريين `main` و `develop`:
|
||||
1. **Require a pull request before merging:** منع الدفع المباشر (`Direct Push`) إلى هذه الفروع.
|
||||
2. **Require approvals:** اشتراط موافقة مطور واحد على الأقل (`1 Approver`) قبل دمج أي Pull Request.
|
||||
3. **Require status checks to pass before merging:** اشتراط اجتياز خط أنابيب التجميع والاختبار (`SteganoPixel CI/CD Pipeline`) بنجاح.
|
||||
4. **Require conversation resolution:** اشتراط حل جميع الملاحظات والتعليقات البرمجية قبل الدمج.
|
||||
5. **Do not allow bypassing the above settings:** تطبيق هذه القواعد على جميع المطورين، بما في ذلك مديري المستودع (Admins).
|
||||
|
||||
---
|
||||
|
||||
## 2. استراتيجية إدارة الفروع (Branching Strategy / GitFlow)
|
||||
|
||||
يعتمد المشروع على نموذج **GitFlow** المنظم. يتم تصنيف الفروع حسب الغرض منها لضمان عدم تداخل التعديلات:
|
||||
|
||||
```text
|
||||
main ──*─────────────────────────────────────*── (Production Releases)
|
||||
\ /
|
||||
develop *──────*─────────────*────────────*──── (Staging / Integration)
|
||||
\ / /
|
||||
feature/* *─────────* / (New Features / Sub-tasks)
|
||||
/
|
||||
hotfix/* *──────── (Urgent Production Bug Fixes)
|
||||
```
|
||||
|
||||
| نوع الفرع | التسمية القياسية | مشتق من | يُدمج إلى | الغرض |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **الإنتاج (Production)** | `main` | — | — | يحتوي دائماً على الشفرة المستقرة والجاهزة للمستخدمين النهائيين. كل دمج هنا يقابله إصدار (Release). |
|
||||
| **التطوير (Integration)** | `develop` | `main` | `main` | الفرع المحوري المجمع للميزات الجديدة. يُستخدم للاختبار الشامل قبل النقل للإنتاج. |
|
||||
| **الميزات (Features)** | `feature/<name>` | `develop` | `develop` | لتطوير ميزة أو صفحة جديدة (مثلاً: `feature/confetti-animation` أو `feature/pdf-support`). |
|
||||
| **الإصلاحات (Bug Fixes)** | `bugfix/<ticket>` | `develop` | `develop` | لإصلاح أخطاء غير حرجة تم اكتشافها أثناء التطوير (مثلاً: `bugfix/download-button-mobile`). |
|
||||
| **الطوارئ (Hotfixes)** | `hotfix/<ticket>`| `main` | `main` و `develop`| لإصلاح أخطاء حرجة جداً في الإنتاج بشكل فوري (مثلاً: `hotfix/lsb-overflow-crash`). |
|
||||
|
||||
---
|
||||
|
||||
## 3. اصطلاحات كتابة رسائل الالتزام (Conventional Commits)
|
||||
|
||||
يعتمد المشروع اصطلاحات الالتزام القياسية العالمية (**Conventional Commits**) لضمان قراءة تاريخ التعديلات بوضوح وتوليد سجل التغييرات (`CHANGELOG.md`) تلقائياً.
|
||||
|
||||
### الهيكل القياسي:
|
||||
```text
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
```
|
||||
|
||||
### أنواع الالتزامات المعتمدة (`Types`):
|
||||
|
||||
| النوع | المعنى | مثال قياسي بالإنجليزية |
|
||||
| :--- | :--- | :--- |
|
||||
| **`feat`** | إضافة ميزة برمجية أو وظيفية جديدة | `feat(steganography): add web worker for asynchronous embedding` |
|
||||
| **`fix`** | إصلاح خطأ برمجي أو بصري | `fix(ui): resolve blob download link issue on mobile browsers` |
|
||||
| **`docs`** | تعديل أو إضافة ملفات التوثيق | `docs(customization): update font replacement instructions` |
|
||||
| **`style`** | تعديلات شكلية لا تؤثر على المنطق (مسافات، فواصل) | `style(components): reformat UploadCard component syntax` |
|
||||
| **`refactor`** | إعادة هيكلة الكود دون إضافة ميزة أو إصلاح خطأ | `refactor(engine): separate bit reading logic into utility fn` |
|
||||
| **`perf`** | تحسينات ترفع من أداء وسرعة التطبيق | `perf(canvas): use requestAnimationFrame to prevent ui freeze` |
|
||||
| **`test`** | إضافة اختبارات آلية جديدة أو تعديل الحالية | `test(engine): add exhaustive suite for LSB 3-channel encode` |
|
||||
| **`build`** | تعديلات على أدوات التجميع أو الحزم (`npm`, `Vite`) | `build(vite): configure static asset inline limit` |
|
||||
| **`ci`** | تعديلات على إعدادات GitHub Actions | `ci(workflow): set output artifact retention days to 7` |
|
||||
|
||||
### قواعد هامة لكتابة الالتزام:
|
||||
1. يجب كتابة الالتزام باللغة **الإنجليزية** لضمان التوافق العالمي.
|
||||
2. يجب أن يبدأ الموضوع فعل أمر بصيغة المضارع (مثال: `add` وليس `added` أو `adds`).
|
||||
3. ألا يتجاوز السطر الأول `72` حرفاً.
|
||||
|
||||
---
|
||||
|
||||
## 4. بروتوكول طلبات الدمج والمراجعة (Pull Request & Code Review)
|
||||
|
||||
لتقديم مساهمة برمجية ناجحة، يُرجى الالتزام بالبروتوكول التالي عند إنشاء طلب دمج (**Pull Request**):
|
||||
|
||||
1. **تحديث الفرع المحلي:** تأكد من عمل `git pull origin develop` ودمج أحدث التغييرات في فرعك قبل إنشاء الـ PR.
|
||||
2. **العنوان القياسي:** استخدم نفس صيغة الالتزامات (مثال: `feat(ui): implement success confetti animations`).
|
||||
3. **استخدام قالب طلب الدمج:** انسخ واملأ القالب التالي في صندوق وصف الـ PR:
|
||||
|
||||
```markdown
|
||||
### 🎯 ملخص التغييرات (Summary of Changes)
|
||||
- [شرح مختصر لما تم إضافته أو إصلاحه في هذا الـ PR]
|
||||
|
||||
### 🔗 التذكرة المتصلة (Related Issue)
|
||||
- يغلق تذكرة رقم: #123
|
||||
|
||||
### 📋 قائمة التحقق (Checklist)
|
||||
- [ ] تم اختبار التغييرات محلياً على أكثر من متصفح (Chrome, Firefox).
|
||||
- [ ] الكود خالي من تعليقات الـ `console.log` والـ `TODO` المنسية.
|
||||
- [ ] تم الالتزام بأفضل ممارسات الـ TypeScript (عدم استخدام `any`).
|
||||
- [ ] تمت إضافة تعليقات توضيحية كاملة لأي جزء منطقي معقد.
|
||||
|
||||
### 🖼️ لقطات شاشة / معاينة (Screenshots / Before & After)
|
||||
| قبل (Before) | بعد (After) |
|
||||
| :---: | :---: |
|
||||
| [ضع صورة هنا إن وجد] | [ضع صورة هنا إن وجد] |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. إدارة الإصدارات والوسوم (Semantic Versioning - SemVer)
|
||||
|
||||
نتبع في **SteganoPixel** معيار التقسيم الدلالي للإصدارات (**SemVer: `MAJOR.MINOR.PATCH`**):
|
||||
|
||||
* **`MAJOR` (الإصدار الرئيسي):** تغييرات جذرية غير متوافقة مع الإصدارات السابقة (مثلاً: تغيير خوارزمية التشفير من LSB إلى خوارزمية DCT معمارية).
|
||||
* **`MINOR` (الإصدار الفرعي):** إضافات وظائف جديدة متوافقة مع الإصدارات السابقة (مثلاً: إضافة خيار حماية النص بكلمة مرور).
|
||||
* **`PATCH` (الإصدار التصحيحي):** إصلاحات أخطاء أو تحسينات أداء طفيفة (مثلاً: إصلاح مشكلة تنزيل الصورة في متصفح سفاري).
|
||||
|
||||
### كيفية إطلاق إصدار جديد (Releasing Protocol):
|
||||
1. قم بإنشاء فرع إصدار مشتق من `develop` (مثال: `release/v1.1.0`).
|
||||
2. حدّث رقم الإصدار في `package.json`.
|
||||
3. ادمج الفرع إلى `main` وإلى `develop`.
|
||||
4. قم بإنشاء وسم Git Tag على الفرع `main`:
|
||||
```bash
|
||||
git tag -a v1.1.0 -m "Release v1.1.0: Enhanced performance and new preview tools"
|
||||
git push origin v1.1.0
|
||||
```
|
||||
5. توجّه إلى صفحة **Releases** في GitHub وأطلق الإصدار رسمياً مع إرفاق سجل التغييرات (`Changelog`).
|
||||
|
||||
---
|
||||
|
||||
## 6. قوالب الإبلاغ عن الأخطاء والميزات (GitHub Issue Templates)
|
||||
|
||||
لتسهيل إدارة المهام، يُنصح بتفعيل مجلد `.github/ISSUE_TEMPLATE` أو الاعتماد على القوالب التالية عند فتح `Issue` جديدة:
|
||||
|
||||
### أ. قالب الإبلاغ عن خطأ (Bug Report Template)
|
||||
```markdown
|
||||
**عنوان التذكرة:** [Bug]: وصف مختصر للخطأ
|
||||
|
||||
**وصف الخطأ:**
|
||||
[اشرح الخطأ بالتفصيل وما الذي حدث خلافاً للمتوقع]
|
||||
|
||||
**خطوات إعادة التكرار (Steps to Reproduce):**
|
||||
1. اذهب إلى صفحة '...'
|
||||
2. ارفع صورة من نوع '...'
|
||||
3. اضغط على زر '...'
|
||||
4. شاهد الخطأ
|
||||
|
||||
**السلوك المتوقع (Expected Behavior):**
|
||||
[ما الذي كان يفترض أن يحدث؟]
|
||||
|
||||
**البيئة (Environment):**
|
||||
- نظام التشغيل: [مثال: Windows 11 / macOS 14]
|
||||
- المتصفح وإصداره: [مثال: Chrome 122]
|
||||
- حجم الصورة ونوعها: [مثال: 5MB PNG]
|
||||
```
|
||||
|
||||
### ب. قالب طلب ميزة (Feature Request Template)
|
||||
```markdown
|
||||
**عنوان التذكرة:** [Feature]: اسم الميزة المقترحة
|
||||
|
||||
**المشكلة التي تحلها الميزة:**
|
||||
[اشرح الصعوبة أو المشكلة الحالية التي تواجه المستخدمين]
|
||||
|
||||
**الحل المقترح (Proposed Solution):**
|
||||
[اشرح كيف ستعمل الميزة الجديدة وكيف ستعزز من قدرات التطبيق]
|
||||
|
||||
**بدائل تم التفكير فيها (Alternatives Considered):**
|
||||
[أي طرق أخرى فكرت فيها لحل المشكلة]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. الأتمتة المدمجة (GitHub Actions CI/CD Pipeline)
|
||||
|
||||
يحتوي المستودع على خط أنابيب مؤتمت بالكامل معرّف في `.github/workflows/ci.yml`. يعمل هذا الخط تلقائياً عند أي عملية `push` أو `pull_request` على فروع التطوير والإنتاج لضمان الجودة.
|
||||
|
||||
### المهام التي ينفذها خط الأنابيب (CI Workflow):
|
||||
1. **التحقق من التنسيق (Linting):** فحص الكود والتأكد من خلوه من الأخطاء البنيوية.
|
||||
2. **فحص التنميط (Type Checking):** تشغيل مترجم `TypeScript` الصارم لضمان عدم وجود تناقض في الأنواع.
|
||||
3. **تجميع الإنتاج (Production Build):** تنفيذ الأمر `npm run build` للتأكد من أن تطبيق `Vite` قادر على تحويل الكود بالكامل إلى مجلد `dist/` سليم.
|
||||
4. **حفظ المخرجات (Artifacts):** حفظ المخرجات النهائية المجمعة لمدة 7 أيام ليتمكن المطورون من تنزيلها وفحصها.
|
||||
31
index.html
Normal file
31
index.html
Normal file
@@ -0,0 +1,31 @@
|
||||
<!doctype html>
|
||||
<html lang="ar" dir="rtl">
|
||||
<!--
|
||||
ملف المستند الأساسي (Root HTML Document) - SteganoPixel
|
||||
=======================================================
|
||||
الجزء الأول من الشرح الهيكلي:
|
||||
يمثل هذا الملف الهيكل العظمي لتطبيق الويب (Single Page Application). تم إعداده بشكل كامل لدعم اللغة العربية
|
||||
(lang="ar" dir="rtl") من الألف إلى الياء. يحتوي على جميع وسوم البيانات الوصفية (Meta Tags) الضرورية لتحسين
|
||||
محركات البحث (SEO) وضبط أبعاد العرض التجاوبي (Viewport) ليلائم جميع مقاسات الشاشات من الهواتف حتى الشاشات العملاقة.
|
||||
|
||||
الجزء الثاني من الشرح الهيكلي:
|
||||
يستضيف هذا الملف الحاوية الجذرية (<div id="root"></div>) التي يقوم محرك React بتركيب شجرة المكونات التفاعلية
|
||||
داخلها (عبر src/main.tsx). كما يربط حزم الجافاسكربت الحديثة بنظام الوحدات (type="module")، ما يتيح لأداة Vite
|
||||
حقن التحديثات الفورية أثناء التطوير وتجميع الكود بأعلى كفاءة ممكنة عند التصدير للإنتاج.
|
||||
-->
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta
|
||||
name="description"
|
||||
content="ستيجانو بكسل (SteganoPixel) - تطبيق ويب عربي متطور لإخفاء النصوص السرية داخل الصور الرقمية بأسلوب غير ملحوظ بصرياً واستخراجها أو تنظيفها بأمان تام داخل المتصفح."
|
||||
/>
|
||||
<meta name="keywords" content="إخفاء النص في الصورة, ستيجانوغرافي, تشفير النصوص, steganography, LSB, steganopixel" />
|
||||
<meta name="author" content="SteganoPixel Application" />
|
||||
<title>ستيجانو بكسل (SteganoPixel) - إخفاء واستخراج النصوص في الصور</title>
|
||||
</head>
|
||||
<body>
|
||||
<div id="root"></div>
|
||||
<script type="module" src="/src/main.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
المرجع في مشكلة جديدة
حظر مستخدم