# دليل التركيب التفصيلي وشرح الأوامر - Smart Pharmacy Hub

هذا الدليل مخصص لرفع المشروع على موقع رئيسي وربطه بقواعد بيانات. يحتوي على أوامر التشغيل محليا، أوامر الإنتاج، وطريقة إعداد PostgreSQL وRedis وOpenSearch.

## 1. المتطلبات قبل التركيب

ثبت البرامج التالية على جهازك أو الخادم:

```bash
node -v
npm -v
docker --version
docker compose version
```

المطلوب:

- Node.js 20 أو أحدث.
- npm.
- Docker وDocker Compose إذا أردت تشغيل قواعد البيانات محليا أو على VPS.
- خادم Linux أو Windows Server أو استضافة تدعم Node.js.

## 2. محتويات المشروع

```text
web/
```

واجهة الويب الرئيسية. تحتوي على `index.html` وتعمل مباشرة في المتصفح أو عبر `web/server.js`.

```text
backend/
```

خادم API مبني بـ NestJS. يستخدم لاحقا للربط الحقيقي مع قاعدة البيانات وتسجيل الدخول والصلاحيات.

```text
database/
```

إعداد قواعد البيانات والخدمات المساندة:

- PostgreSQL للبيانات الأساسية.
- Redis للكاش والجلسات.
- OpenSearch للبحث المتقدم.

```text
docs/
```

التصميم المعماري، OpenAPI، مخطط قاعدة البيانات، وخطة المشروع.

```text
mobile/android
mobile/apple
```

مجلدات منفصلة لتوثيق تطبيقات Android وApple/iOS.

## 3. تشغيل الواجهة محليا

افتح PowerShell أو Terminal من جذر المشروع:

```bash
cd web
node server.js
```

ثم افتح:

```text
http://127.0.0.1:8082
```

إذا أردت تغيير المنفذ:

```powershell
cd web
$env:PORT=8090
node server.js
```

ثم افتح:

```text
http://127.0.0.1:8090
```

## 4. رفع الواجهة على موقع رئيسي Static

إذا كانت الاستضافة مثل cPanel أو Plesk أو Netlify أو Vercel Static:

1. افتح مجلد `web`.
2. ارفع ملف `index.html` إلى مجلد الموقع الرئيسي:

```text
public_html/
```

أو:

```text
wwwroot/
```

ملاحظات:

- ملف `server.js` لا تحتاجه في الاستضافة الثابتة.
- إذا كان الموقع يعمل على Node.js VPS، يمكنك تشغيل `server.js`.
- بعد الرفع افتح الدومين وتأكد من تبديل اللغة عربي/إنجليزي.

## 5. تشغيل Backend محليا

من جذر المشروع:

```bash
cd backend
npm install
```

شرح الأمر:

- `npm install` يثبت كل مكتبات المشروع داخل `node_modules`.

شغل Backend بوضع التطوير:

```bash
npm run start:dev
```

شرح الأمر:

- يشغل NestJS مع مراقبة التغييرات.
- مناسب أثناء التطوير فقط.

بناء نسخة إنتاج:

```bash
npm run build
```

شرح الأمر:

- يفحص TypeScript.
- ينشئ مجلد `dist`.

تشغيل النسخة المبنية:

```bash
npm run start
```

## 6. إعداد ملف البيئة Backend

انسخ ملف المثال:

```powershell
cd backend
copy .env.example .env
```

على Linux:

```bash
cd backend
cp .env.example .env
```

ثم عدل `backend/.env`:

```env
PORT=3000
JWT_SECRET=replace_with_strong_secret
DATABASE_URL=postgresql://smart_user:strong_password@localhost:5432/smart_pharmacy_hub
REDIS_URL=redis://localhost:6379
OPENSEARCH_URL=http://localhost:9200
```

شرح القيم:

- `PORT`: منفذ تشغيل API.
- `JWT_SECRET`: مفتاح توقيع تسجيل الدخول، يجب تغييره في الإنتاج.
- `DATABASE_URL`: رابط PostgreSQL.
- `REDIS_URL`: رابط Redis.
- `OPENSEARCH_URL`: رابط محرك البحث.

## 7. تشغيل قواعد البيانات عبر Docker

من جذر المشروع:

```bash
cd database
docker compose up -d
```

شرح الأمر:

- يشغل PostgreSQL وRedis وOpenSearch في الخلفية.
- الخيار `-d` يعني Detached Mode.

عرض الخدمات:

```bash
docker compose ps
```

مشاهدة السجلات:

```bash
docker compose logs -f
```

إيقاف الخدمات:

```bash
docker compose down
```

إيقاف وحذف البيانات بالكامل:

```bash
docker compose down -v
```

تنبيه: الأمر السابق يحذف بيانات قاعدة البيانات، لا تستخدمه في الإنتاج إلا إذا كنت متأكدا.

## 8. إنشاء الجداول في PostgreSQL

ملفات SQL موجودة هنا:

```text
database/postgres/01_extensions.sql
database/postgres/02_core_schema.sql
```

إذا كانت قاعدة البيانات تعمل عبر Docker Compose، فغالبا سيتم تنفيذ ملفات init عند أول تشغيل للحاوية.

للتنفيذ اليدوي:

```bash
docker exec -it smart-pharmacy-postgres psql -U smart_user -d smart_pharmacy_hub
```

ثم داخل PostgreSQL:

```sql
\dt
```

لعرض الجداول.

أو من خارج الحاوية:

```bash
psql "postgresql://smart_user:strong_password@localhost:5432/smart_pharmacy_hub" -f database/postgres/01_extensions.sql
psql "postgresql://smart_user:strong_password@localhost:5432/smart_pharmacy_hub" -f database/postgres/02_core_schema.sql
```

## 9. رفع Backend على VPS

على الخادم:

```bash
cd /var/www
unzip smart-pharmacy-hub-production-ready.zip
cd backend
npm install
npm run build
```

شغل API باستخدام PM2:

```bash
npm install -g pm2
pm2 start dist/main.js --name smart-pharmacy-api
pm2 save
pm2 startup
```

شرح الأوامر:

- `pm2 start`: تشغيل API كخدمة مستمرة.
- `pm2 save`: حفظ قائمة الخدمات.
- `pm2 startup`: تشغيل الخدمات تلقائيا بعد إعادة تشغيل السيرفر.

## 10. ربط الدومين

تقسيم مقترح:

```text
https://your-domain.com
```

واجهة المستخدم.

```text
https://api.your-domain.com
```

خادم API.

مثال Nginx للواجهة:

```nginx
server {
  listen 80;
  server_name your-domain.com;
  root /var/www/smart-pharmacy/web;
  index index.html;

  location / {
    try_files $uri /index.html;
  }
}
```

مثال Nginx للـ API:

```nginx
server {
  listen 80;
  server_name api.your-domain.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
```

بعد ذلك فعّل HTTPS باستخدام Certbot:

```bash
sudo certbot --nginx -d your-domain.com -d api.your-domain.com
```

## 11. ربط الواجهة بالـ API

الواجهة الحالية Prototype مستقل. عند ربطها فعليا بالـ Backend:

1. أضف متغير API Base URL.
2. استبدل البيانات التجريبية بطلبات `fetch`.
3. اجعل الطلبات تتجه إلى:

```text
https://api.your-domain.com/v1
```

أمثلة Endpoints موثقة في:

```text
docs/openapi.yaml
```

## 12. أوامر الفحص قبل الرفع

فحص JavaScript للواجهة:

```bash
node --check web/server.js
```

فحص Backend:

```bash
cd backend
npm run build
```

فحص تشغيل الموقع المحلي:

```powershell
Invoke-WebRequest -Uri http://127.0.0.1:8082 -UseBasicParsing
```

## 13. ضغط المشروع يدويا

لا تضغط `node_modules` أو `dist` لأنها ملفات توليد ويمكن إنشاؤها بالأوامر.

PowerShell:

```powershell
Compress-Archive -Path web,backend,database,docs,mobile,README.md,README_COMMANDS_AR.md,DEPLOYMENT_AR.md,INSTALLATION_DATABASE_AR.md -DestinationPath smart-pharmacy-hub-production-ready.zip -Force
```

## 14. قائمة تحقق بعد الرفع

افتح الموقع وتأكد من:

- تسجيل الدخول يعمل.
- زر اللغة في صفحة التسجيل يعمل.
- العربية RTL والإنجليزية LTR تعملان.
- مركز التنبيهات يترجم بالكامل.
- ملف المريض يعمل.
- إعادة صرف الدواء تعمل.
- التحاليل والأشعة تعمل.
- التأمين والرعاية المنزلية تظهران.
- لا يوجد خطأ في Console.

## 15. ملاحظات أمان مهمة

- غيّر `JWT_SECRET`.
- لا ترفع `.env` إلى GitHub.
- استخدم HTTPS.
- فعّل نسخ احتياطي يومي لقاعدة البيانات.
- استخدم كلمات مرور قوية.
- لا تستخدم بيانات مرضى حقيقية قبل تفعيل التشفير وسياسات الخصوصية والموافقات.
- راجع صلاحيات الأدوار في:

```text
docs/roles-permissions-ar.md
```