# تثبيت نظام سجلات الطلاب على لابتوب مع MySQL مستقلة

هذا الدليل يشغّل **التطبيق** و**قاعدة البيانات** كجزأين منفصلين: ملفات التطبيق تبقى داخل مجلد المشروع، بينما تبقى قاعدة MySQL في خدمة MySQL نفسها؛ لذلك يمكن أخذ نسخة احتياطية واستعادتها أو نقلها دون نسخ مجلد التطبيق.

> احتفظي بملف `.env` ونسخة قاعدة البيانات في مكان آمن. لا تضعي كلمات المرور أو ملف النسخ الاحتياطي في مساحة عامة.

## المتطلبات

| المكوّن | المطلوب |
|---|---|
| نظام التشغيل | Windows 10/11 أو Ubuntu/Linux حديث |
| Node.js | الإصدار 22 أو أحدث |
| pnpm | الإصدار 10 أو أحدث |
| MySQL | الإصدار 8 أو أحدث |
| متصفح | Chrome أو Edge أو Firefox |

## 1. إنشاء قاعدة MySQL مستقلة

افتحي MySQL كمسؤول وأنشئي قاعدة ومستخدم التطبيق. استبدلي كلمة المثال بكلمة قوية:

```sql
CREATE DATABASE student_records CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'student_app'@'localhost' IDENTIFIED BY 'CHANGE_THIS_TO_A_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON student_records.* TO 'student_app'@'localhost';
FLUSH PRIVILEGES;
```

فكي ضغط ملفات المشروع في `C:\student-records` على Windows أو `/opt/student-records` على Linux، ثم أنشئي الجداول:

```bash
mysql -u student_app -p student_records < docs/local-schema.sql
```

في PowerShell:

```powershell
Get-Content docs\local-schema.sql | mysql -u student_app -p student_records
```

## 2. إعداد التطبيق

انسخي ملف البيئة ثم عدّلي القيم:

```bash
cp docs/env.local.example .env
pnpm install
pnpm build
```

في Windows PowerShell:

```powershell
Copy-Item docs\env.local.example .env
pnpm install
pnpm build
```

مثال أهم المتغيرات في `.env`:

```env
DATABASE_URL=mysql://student_app:CHANGE_THIS_TO_A_STRONG_PASSWORD@127.0.0.1:3306/student_records
LOCAL_AUTH_ENABLED=true
VITE_LOCAL_AUTH_ENABLED=true
LOCAL_ADMIN_USERNAME=admin
LOCAL_ADMIN_PASSWORD=PUT_A_STRONG_ADMIN_PASSWORD_HERE
```

شغّلي التطبيق:

```bash
NODE_ENV=production pnpm start
```

وفي PowerShell:

```powershell
$env:NODE_ENV="production"; pnpm start
```

أو استخدمي سكربت التشغيل الجاهز في PowerShell:

```powershell
.\scripts\run-local.ps1
```

افتحي `http://localhost:3000` على اللابتوب. وللوصول من هاتف أو جهاز ضمن الشبكة الداخلية، استخدمي عنوان IP للجهاز مثل `http://192.168.1.20:3000` بعد السماح للمنفذ 3000 في جدار الحماية للشبكة الخاصة فقط.

## 3. الاستخدام والصلاحيات

ادخلي من `/local-login` بحساب المدير المحدد في `.env`. من قائمة **المستخدمون** يستطيع المدير إنشاء الحسابات وتحديد رتبتها وكلمة مرورها وإيقاف حسابات المحررين وإعادة تعيين كلمات مرورهم.

| الرتبة | الوصول المسموح |
|---|---|
| `admin` | إدارة الحسابات، إدارة سجلاته الخاصة، وفتح صفحة **تقاريري** وتنزيل PDF بعد فلترة تاريخ الإدخال. |
| `editor` | الدخول وإضافة وتعديل وحذف واستيراد والبحث ضمن سجلاته الخاصة فقط. لا تظهر له التقارير ولا يمكنه طلبها من الخادم. |

التقرير معزول بحساب المدير الحالي؛ لا يعرض سجلات محرر أو مدير آخر. رقم الجلوس ورقم الاستمارة البنكية يظلان فريدين على مستوى قاعدة MySQL كلها.

إذا كانت لديك قاعدة محلية قديمة أنشئت قبل دور `editor`، طبقي هذا الترحيل مرة واحدة بحساب MySQL المسؤول:

```sql
ALTER TABLE users MODIFY COLUMN role ENUM('user','editor','admin') NOT NULL DEFAULT 'editor';
UPDATE users SET role = 'editor' WHERE role = 'user';
```

رقم الجلوس ورقم الاستمارة البنكية فريدان على مستوى قاعدة MySQL كلها. إذا أُدخل رقم مستخدم بالفعل، تعرض المنصة رسالة عامة دون كشف مالك السجل.

## 4. تصدير واستيراد قاعدة البيانات

أنشئي مجلد النسخ خارج مجلد المشروع، مثل `D:\Backups\StudentRecords` أو قرص خارجي.

```bash
mysqldump -u student_app -p --single-transaction --routines --events --databases student_records > backups/student_records_YYYY-MM-DD.sql
```

لاستعادة النسخة إلى MySQL:

```bash
mysql -u student_app -p < backups/student_records_YYYY-MM-DD.sql
```

وتتوفر سكربتات Windows الجاهزة أيضاً:

```powershell
.\scripts\backup-mysql.ps1
.\scripts\restore-mysql.ps1 -BackupFile .\backups\student_records_YYYY-MM-DD.sql
```

اختبري الاستعادة أولاً على قاعدة تجريبية. لا توجد مدة انتهاء برمجية للنظام؛ استمراره يعتمد على بقاء اللابتوب أو الخادم والتطبيق وMySQL والنسخ الاحتياطية متاحة.