# توثيق مشروع 7 Tech > المرجع الشامل لبنية المشروع، التشغيل، لوحة الإدارة، الـAPI، قاعدة البيانات، الأمان، الاختبارات والنشر. **آخر تحديث:** 18 أغسطس 2026 **نوع المشروع:** Laravel Modular Monolith **الترخيص:** Proprietary ## 1. نظرة عامة المشروع هو منصة Backend ولوحة إدارة متكاملة لشركة **7 Tech**. يدير الموقع العام، المحتوى، الخدمات، العملاء، المشاريع، الشركاء، المدونة، الوظائف، طلبات التوظيف، التسعير، الاجتماعات، CRM، عروض الأسعار، التحليلات، الذكاء الاصطناعي، التكاملات وSEO. عند فتح المسار الرئيسي `/`: - الزائر غير المسجل يُحوّل إلى `/login`. - المستخدم المسجل صاحب صلاحية لوحة التحكم يُحوّل إلى `/admin`. - المستخدم الذي لا يملك صلاحية لوحة التحكم يُحوّل إلى صفحة أمان الحساب. يدعم المشروع: - العربية والإنجليزية مع RTL/LTR. - الوضع الفاتح والداكن. - صلاحيات ديناميكية مبنية على الأدوار. - مصادقة ثنائية للحسابات الحساسة. - API v1 باستخدام Bearer Tokens. - سجل تدقيق وأرشفة محمية بكلمة مرور المدير. - رفع صور داخل كل صفحة وربطها بالسجل الخاص بها. - الحذف المؤقت وسلة المحذوفات والاسترجاع والحذف النهائي. ## 2. التقنيات المستخدمة | الجزء | التقنية | |---|---| | Backend | PHP 8.4+ | | Framework | Laravel 13 | | Authentication | Laravel Fortify | | Production Database | MySQL 8+ / `utf8mb4` | | Local/Test Database | SQLite | | Cache / Queue / Locks | Redis موصى به للإنتاج | | UI | Blade + Tailwind CSS 4 | | Bundler | Vite 8 | | Charts | Chart.js 4 | | Package Manager | pnpm 11 | | Tests | PHPUnit 12 | | Static Analysis | Larastan / PHPStan | | Formatting | Laravel Pint | الخطوط المستخدمة: - Inter للإنجليزية. - IBM Plex Sans Arabic للعربية. ## 3. بنية المجلدات ```text 7-backend-/ ├── app/ │ ├── Console/Commands/ أوامر Artisan الخاصة بالمشروع │ ├── Foundation/ API، Audit، Notifications، Trash، Operations │ ├── Http/ │ │ ├── Controllers/ Web، Admin، Public، API │ │ ├── Middleware/ المصادقة، الصلاحيات، الأمان، اللغة │ │ └── Requests/ التحقق من المدخلات │ ├── Modules/ وحدات العمل المستقلة │ ├── Providers/ تسجيل الخدمات وسياسات التشغيل │ └── View/ التنقل ومكونات Blade ├── bootstrap/app.php Middleware ومعالجة أخطاء API ├── config/ إعدادات المشروع ├── database/ │ ├── factories/ │ ├── migrations/ │ └── seeders/ ├── docs/ وثائق معمارية وAPI وحزم Postman ├── lang/ ترجمات العربية والإنجليزية ├── public/ نقطة الدخول وملفات Vite المبنية ├── resources/ │ ├── css/app.css │ ├── js/ │ └── views/ ├── routes/ │ ├── api.php │ ├── console.php │ └── web.php ├── storage/ logs، sessions، cache، uploads الخاصة ├── tests/ Unit وFeature Tests ├── .env.example نموذج إعداد البيئة ├── composer.json ├── package.json └── vite.config.js ``` ## 4. الوحدات الرئيسية | الوحدة | المسؤولية | |---|---| | Identity | المستخدمون، تسجيل الدخول، كلمات المرور، 2FA، الجلسات والتوكنات | | AccessControl | الأدوار، الصلاحيات، Super Admin وسياسات الوصول | | Analytics | الأحداث، المقاييس اليومية والداشبورد التنفيذي | | Company | بيانات الشركة، من نحن وتواصل معنا | | Content | الرئيسية، شريط التنقل، Footer والمحتوى القابل للنشر | | Catalog | الخدمات، القوالب، التصنيفات والصناعات والخصائص | | Media | الصور والملفات وربطها بصفحات المشروع | | Portfolio | العملاء، المشاريع، الأعمال والشركاء | | Publishing | المدونة، النسخ، الجدولة والنشر | | Recruitment | الوظائف، الطلبات وملفات CV | | Pricing | العملات، قوائم الأسعار، الباقات وقواعد التسعير | | Scheduling | أنواع الاجتماعات، المواعيد وقواعد التوفر | | Crm | جهات الاتصال والعملاء المحتملون | | Quotations | طلبات المشاريع وعروض الأسعار | | Ai | مزودو الذكاء الاصطناعي والوكلاء والتوصيات | | Integrations | الاتصالات الخارجية وOutbox والتسليمات | | Seo | Metadata، Redirects، Sitemap وRobots | | Settings | إعدادات النظام المُدارة | داخل معظم الوحدات يُفصل الكود إلى: ```text Domain/ Models، Enums وقواعد المجال Application/ Managers وUse Cases Policies/ سياسات الصلاحيات ``` ## 5. صفحات لوحة الإدارة يُبنى الشريط الجانبي حسب صلاحيات المستخدم، ويحتوي على المجموعات التالية: ### مساحة العمل - نظرة عامة `/admin`. ### التحكم في الوصول - المستخدمون. - الأدوار والصلاحيات. ### العمليات - سجل التدقيق. - سجل الأرشفة اليدوي المحمي بكلمة مرور المدير. - نتائج إرسال الإشعارات. - سلة المحذوفات من داخل قسم العمليات. ### الأقسام - شريط التنقل. - الرئيسية. - من نحن. - الخدمات. - عملاؤنا. - أعمالنا. - شركاؤنا. - المدونة. - الوظائف، وتتضمن سيكشن طلبات التوظيف بداخلها. - تواصل معنا. - اطلب مشروعك. - Footer. ### الوحدات التشغيلية - التسعير. - الاجتماعات. - CRM وعروض الأسعار. - الذكاء الاصطناعي. - التكاملات. - SEO. - أمان الحساب. ## 6. صفحات الموقع العامة | Method | Path | الوظيفة | |---|---|---| | GET | `/` | تسجيل الدخول أو التحويل حسب حالة المستخدم | | GET | `/about` | من نحن | | GET | `/contact` | تواصل معنا | | GET | `/services` | قائمة الخدمات | | GET | `/services/ui-ux-design` | مثال جاهز لتفاصيل خدمة (`/services/{slug}` هو نمط المسار فقط) | | GET | `/work` | الأعمال والمشاريع | | GET | `/portfolio/texas-logistics-platform` | مثال جاهز لدراسة حالة مشروع (`/portfolio/{slug}` هو نمط المسار فقط) | | GET | `/partners` | الشركاء | | GET | `/blog` | المدونة | | GET | `/blog/{post}` | تفاصيل المقال | | GET | `/careers` | الوظائف | | GET | `/careers/{job}` | تفاصيل الوظيفة | | POST | `/careers/{job}/applications` | إرسال طلب توظيف | | GET/POST | `/book` | حجز اجتماع | | GET/POST | `/quote` | طلب مشروع أو عرض سعر | | GET | `/sitemap.xml` | Sitemap | | GET | `/robots.txt` | Robots rules | | GET | `/health/ready` | فحص جاهزية الخدمات | طلبات الحجز، عروض الأسعار والتوظيف محمية بـRate Limiting. ## 7. المصادقة والحسابات ### تسجيل الدخول ```text GET /login POST /login ``` ### استعادة كلمة المرور ```text GET /forgot-password POST /forgot-password GET /reset-password/{token} POST /reset-password ``` ### إنشاء مستخدم ينشئ المدير المستخدم ويحدد له: - الاسم أو المسمى الوظيفي. - البريد الإلكتروني. - كلمة المرور. - الأدوار والصلاحيات. - حالة الحساب. يمكن إجبار المستخدم على تغيير كلمة المرور عند أول دخول. ### حماية الحسابات الحساسة - الحساب غير النشط لا يمكنه تسجيل الدخول أو استخدام API. - الحسابات الحساسة مطالبة بتأكيد 2FA عندما يكون الإعداد مفعلًا. - العمليات الإدارية تتطلب Password Confirmation. - إنشاء المستخدم وفتح سجل الأرشفة يتطلبان إعادة إدخال كلمة مرور المدير. - إلغاء تنشيط المستخدم يؤدي إلى إلغاء جلساته. ## 8. الأدوار والصلاحيات الدور النظامي الأساسي هو: ```text super-admin ``` الصلاحيات الأساسية: ```text dashboard.view users.manage roles.manage permissions.manage company.manage home.manage footer.manage services.view / services.create / services.update / services.delete categories.manage industries.manage features.manage templates.manage pricing.view / pricing.manage clients.manage projects.manage partners.manage blog.manage media.manage jobs.manage applications.manage meetings.view / meetings.manage contacts.manage leads.manage quotations.view / quotations.manage analytics.view notifications.manage audit-logs.view ai.manage integrations.manage seo.manage settings.manage ``` تتحقق طبقات الوصول باستخدام Policies وGates وMiddleware باسم `permission`. ## 9. API v1 العنوان المحلي الأساسي: ```text http://127.0.0.1:8000/api/v1 ``` ### معلومات API | Method | Endpoint | الوظيفة | |---|---|---| | GET | `/api/v1` | معلومات الإصدار | | GET | `/api/v1/openapi` | OpenAPI Specification | ### Public Content API | Method | Endpoint | |---|---| | GET | `/api/v1/public/navigation` | | GET | `/api/v1/public/menu-bar` | | GET | `/api/v1/public/company` | | GET | `/api/v1/public/home` | | GET | `/api/v1/public/frontend-content` — كل النصوص والصور والأزرار والروابط الثابتة القابلة للتعديل؛ يدعم `?page=home` | | GET | `/api/v1/public/services` | | GET | `/api/v1/public/services/ui-ux-design` — النمط: `/api/v1/public/services/{slug}` | | GET | `/api/v1/public/templates` | | GET | `/api/v1/public/clients` | | GET | `/api/v1/public/projects` | | GET | `/api/v1/public/projects/texas-logistics-platform` — النمط: `/api/v1/public/projects/{slug}` | | GET | `/api/v1/public/portfolio` | | GET | `/api/v1/public/partners` | | GET | `/api/v1/public/posts` | | GET | `/api/v1/public/posts/ai-agents-business` — النمط: `/api/v1/public/posts/{slug}` | | GET | `/api/v1/public/ai-agents-business` — رابط مختصر لنفس المقال | | GET | `/api/v1/public/jobs` | #### إدارة المدونة والمقالات - صفحة الإدارة: `/admin/posts` بصلاحية `blog.manage`. - يمكن تعديل عنوان ووصف صفحة المدونة، التصنيفات وترتيبها، المقال المميز، المقالات الشائعة، عنوان أحدث المقالات، والدعوة الختامية. - يمكن إضافة مقال جديد وتعديل أو حذف مقال موجود. كل مقال يدعم العنوان، التصنيف، الكاتب، وقت القراءة، صورة الغلاف، المقدمة، الوصف المختصر، أقسام محتوى ديناميكية، الخلاصة وCTA مستقل. - `GET /api/v1/public/posts` يعيد إعدادات الصفحة داخل `page` والسيكشنات الجاهزة للفرونت داخل `sections.featured`, `sections.popular`, `sections.latest`. - `GET /api/v1/public/posts/{slug}` يعيد تفاصيل المقال المنشور كاملة. - موارد القراءة المحمية: `blog-page-settings`, `posts`, `post-revisions` عبر `/api/v1/resources/{resource}`. ### إصدار Bearer Token ```http POST /api/v1/auth/token Accept: application/json Content-Type: application/json { "email": "admin@example.com", "password": "your-password", "name": "Postman", "expires_in_days": 1 } ``` استخدم التوكن الناتج في الطلبات المحمية: ```http Authorization: Bearer {public_id}.{secret} Accept: application/json ``` ### إدارة التوكنات | Method | Endpoint | الوظيفة | |---|---|---| | GET | `/api/v1/auth/me` | المستخدم والصلاحيات الفعلية | | GET | `/api/v1/auth/tokens` | توكنات المستخدم | | GET | `/api/v1/auth/token/current` | بيانات التوكن الحالي | | DELETE | `/api/v1/auth/token/current` | إلغاء التوكن الحالي | | DELETE | `/api/v1/auth/tokens/{{token_uuid}}` | إلغاء توكن محدد؛ يتطلب Bearer Token | | DELETE | `/api/v1/auth/tokens` | إلغاء كل توكنات المستخدم | استجابة `204 No Content` عند الحذف الناجح استجابة صحيحة ولا تحتوي Body. ### Resource API ```text GET /api/v1/resources GET /api/v1/resources/{resource} GET /api/v1/resources/{resource}/{identifier} ``` يدعم Endpoint القائمة عادةً: ```text page per_page sort direction q filter[field] ``` كل Resource مربوط بصلاحية محددة، والحقول المعادة موجودة في Allowlist داخل: ```text config/api_fields.php ``` الموارد تشمل المستخدمين، الأدوار، المحتوى، الخدمات، المشاريع، المدونة، الوظائف، التسعير، CRM، الاجتماعات، AI، التكاملات، SEO، التحليلات وسجل التدقيق. ### Dashboard API ```text GET /api/v1/dashboard?from=2026-08-01&to=2026-08-18 ``` يتطلب: ```text analytics.view ``` ### Analytics Ingestion ```text POST /api/analytics/events POST /api/v1/analytics/events ``` ### Postman الملفات الجاهزة: ```text docs/7-tech-api.postman_collection.json docs/7-tech-api-full.postman_collection.json docs/7-tech-local.postman_environment.json docs/ALL-ENDPOINTS-AR.md docs/API.md docs/API-PACKAGE-README-AR.md ``` ## 10. CORS إعداد CORS موجود في: ```text config/cors.php ``` لا يسمح المشروع بـ`Access-Control-Allow-Origin: *`. حدد النطاقات المسموحة مفصولة بفواصل: ```env CORS_ALLOWED_ORIGINS=https://admin.7tech.com,https://7tech.com ``` إذا لم يُحدد المتغير، يُستخدم Origin الخاص بـ`APP_URL`. ## 11. الصور والملفات ### الصور - ترفع الصور من داخل الصفحة التابعة لها. - يمكن الإضافة والاستبدال وتعديل الوصف والترتيب والحذف. - الأدوار المدعومة تشمل `hero` و`gallery` و`thumbnail` و`logo` و`background`. - يُتحقق من MIME الحقيقي وليس اسم الامتداد فقط. - تُخزن الملفات بأسماء UUID. - الحد الافتراضي للصورة 10MB. - الصور العامة لا تُعرض إلا إذا كانت جاهزة ومربوطة بسجل موجود. ### ملفات CV - يقبل طلب التوظيف PDF فقط. - الملف خاص ولا يمكن تنزيله إلا بصلاحية إدارة الطلبات. - إذا فقد الملف من التخزين يعيد النظام 404 ولا ينشئ بديلًا وهميًا. ### ملفات المشاريع ZIP أو Folder - الحد الأقصى 200MB. - الحد الأقصى 2000 عنصر. - تُرفض المسارات المطلقة و`../`. - يُفحص الحجم الإجمالي بعد فك الضغط للحماية من ZIP Bombs. - تُحفظ النسخة النهائية في Private Storage. ### سجل الأرشفة اليدوي - يسمح للمدير بحفظ وصف أو ملف. - يُحسب SHA-256 للملف. - فتح السجل والتنزيل والحذف تتطلب صلاحية وكلمة مرور المدير المؤكدة. ## 12. قاعدة البيانات الإنتاج يستهدف MySQL 8+ مع: ```env DB_CONNECTION=mysql DB_CHARSET=utf8mb4 DB_COLLATION=utf8mb4_unicode_ci ``` المخطط يغطي: - Users، Sessions وPassword Reset Tokens. - Roles، Permissions والعلاقات بينهما. - Authentication Events وAudit Logs/Archives. - Analytics Events وDaily Metrics. - Company، Home Content، Menu Bar وFooter. - Catalog، Services، Templates وMedia. - Pricing، Packages، Price Lists وRules. - Clients، Projects، Partners، Posts وJobs. - Applications، Meetings، CRM وQuotations. - AI Providers/Agents/Runs. - Integrations، Outbox وSEO. - Soft Deletes وسلة المحذوفات. مخطط تفصيلي موجود في: ```text docs/architecture/database-blueprint.md ``` ## 13. التثبيت المحلي ### المتطلبات - PHP 8.4 أو أحدث مع `pdo_sqlite` أو `pdo_mysql` و`mbstring` و`openssl` و`fileinfo` و`zip`. - Composer. - Node.js وpnpm. - MySQL عند استخدام إعداد الإنتاج محليًا. ### الخطوات ```bash composer install copy .env.example .env php artisan key:generate php artisan migrate --seed pnpm install pnpm run build php artisan serve ``` أو: ```bash composer setup ``` الرابط المحلي: ```text http://127.0.0.1:8000/login ``` لا تحفظ بيانات الدخول داخل ملفات Markdown أو Git. يتم إنشاء المدير الأول من متغيرات البيئة الخاصة بـ`InitialCeoSeeder` ثم تُزال القيم الحساسة من البيئة بعد الإنشاء. ## 14. التشغيل أثناء التطوير في نافذة أولى: ```bash php artisan serve ``` وفي نافذة ثانية: ```bash pnpm run dev ``` أو استخدم: ```bash composer dev ``` عند تغيير ملفات البيئة أو الإعدادات: ```bash php artisan optimize:clear ``` ## 15. Seeders الـSeeders الرئيسية: ```text AccessControlSeeder AnalyticsSeeder CompanyContentSettingsSeeder InitialCeoSeeder MenuBarSeeder ServicesCatalogSeeder PortfolioAndPartnersSeeder BlogArticlesSeeder ``` لتشغيلها: ```bash php artisan db:seed ``` أو إعادة بناء قاعدة محلية بالكامل: ```bash php artisan migrate:fresh --seed ``` > هذا الأمر يحذف قاعدة البيانات الحالية؛ لا تستخدمه على بيانات حقيقية. ## 16. الأوامر المجدولة | الجدول | الأمر | الوظيفة | |---|---|---| | كل دقيقة | `db:monitor` | مراقبة اتصالات قاعدة البيانات | | يوميًا 02:10 | `queue:prune-failed` | حذف Failed Jobs القديمة | | يوميًا 02:20 | `queue:prune-batches` | تنظيف Queue Batches | | يوميًا 02:30 | `audit:archive` | أرشفة سجل التدقيق | | كل ساعة عند الدقيقة 10 | `analytics:aggregate --days=2` | تجميع التحليلات | | كل دقيقة | `content:publish-due` | نشر محتوى الرئيسية المستحق | | كل دقيقة | `posts:publish-due` | نشر المقالات المستحقة | | كل دقيقة | `integrations:dispatch-outbox` | إرسال رسائل التكاملات | في الإنتاج يجب تشغيل: ```bash php artisan schedule:work php artisan queue:work ``` أو إعداد Cron يستدعي `schedule:run` كل دقيقة. ## 17. الاختبارات والجودة تشغيل الاختبارات: ```bash composer test ``` التحليل الساكن: ```bash composer analyse ``` فحص التنسيق: ```bash composer lint ``` إصلاح التنسيق: ```bash composer lint:fix ``` تشغيل بوابة الجودة كاملة: ```bash composer quality ``` بناء الواجهة: ```bash pnpm run build ``` الحالة الموثقة بعد آخر فحص أمني: - 237 اختبارًا ناجحًا. - 2013 Assertion ناجحة. - بناء Vite ناجح. - لا توجد ثغرات معروفة في Composer أو npm وقت الفحص. ## 18. الأمان الحماية المطبقة: - CSRF على Web Forms. - Bearer Token Hashing باستخدام SHA-256. - Rate Limiting على تسجيل الدخول وAPI والنماذج العامة. - Content Security Policy. - `X-Content-Type-Options: nosniff`. - `X-Frame-Options: SAMEORIGIN`. - Referrer Policy وPermissions Policy. - HSTS عند تفعيله على HTTPS. - Trusted Hosts وTrusted Proxies. - Session Cookies من نوع HttpOnly وSameSite. - تشفير Session Payload في الإنتاج. - Allowlist لحقول API. - عدم تضمين كلمات المرور والتوكنات والأسرار في الاستجابات. - Request ID لتتبع الأخطاء. - إعداد Production fail-closed يمنع التشغيل بإعدادات غير آمنة. التقرير الأمني التفصيلي: ```text SECURITY_AUDIT.md ``` ## 19. إعدادات Production الأساسية مثال مختصر: ```env APP_ENV=production APP_DEBUG=false APP_URL=https://admin.7tech.com RELEASE_ID=release-2026.08.18 CORS_ALLOWED_ORIGINS=https://admin.7tech.com,https://7tech.com TRUSTED_HOSTS=^admin\.7tech\.com$,^7tech\.com$ DB_CONNECTION=mysql SESSION_DRIVER=database SESSION_ENCRYPT=true SESSION_SECURE_COOKIE=true CACHE_STORE=redis QUEUE_CONNECTION=redis QUEUE_AFTER_COMMIT=true SECURITY_CSP_ENABLED=true SECURITY_HSTS_ENABLED=true AUTH_AUDIT_HASH_KEY= ANALYTICS_HASH_KEY= ``` يجب أيضًا: - استخدام HTTPS. - توفير `APP_KEY` قوي. - عدم وضع أسرار حقيقية في Git. - تشغيل Migrations قبل تحويل الترافيك. - تشغيل Queue Workers وScheduler. - إعداد نسخ احتياطية واختبار الاسترجاع. - تشغيل `php artisan optimize` بعد ضبط البيئة. وثائق النشر: ```text docs/operations/production-readiness.md docs/operations/production-certification.md ``` ## 20. استكشاف الأخطاء ### ظهور 401 من API تحقق من: ```http Authorization: Bearer public_id.secret Accept: application/json ``` أصدر التوكن من: ```http POST /api/v1/auth/token ``` ### ظهور 403 - المستخدم مسجل لكنه لا يملك الصلاحية المطلوبة. - الحساب يحتاج تغيير كلمة المرور أو تأكيد 2FA. - صفحة الأرشيف تحتاج تأكيد كلمة مرور المدير. ### ظهور 404 في Endpoint - تأكد من Method الصحيح؛ مسارات الإلغاء تستخدم `DELETE`. - اعرض المسارات: ```bash php artisan route:list ``` ### تغييرات `.env` لا تظهر ```bash php artisan optimize:clear ``` ### الصور لا تظهر - تأكد من صلاحية MIME والحجم. - تأكد أن السجل محفوظ وأن الصورة مربوطة به. - راجع صلاحيات الكتابة على `storage/`. ### أخطاء Queue ```bash php artisan queue:failed php artisan queue:retry all ``` ### Logs ```text storage/logs/laravel.log ``` ## 21. الوثائق الإضافية ```text docs/architecture/domain-map.md docs/architecture/database-blueprint.md docs/architecture/decisions/ docs/modules/ docs/operations/local-development.md docs/operations/production-readiness.md docs/API.md SECURITY_AUDIT.md ``` ## 22. قواعد المساهمة قبل اعتبار أي تعديل مكتملًا: 1. استخدم Form Request للتحقق من المدخلات. 2. طبّق Policy أو Permission على العملية. 3. لا تستخدم حقول الطلب مباشرة في Mass Assignment. 4. لا تُعد أسرارًا أو حقولًا غير موجودة في API Allowlist. 5. أضف Audit Event للعمليات الحساسة. 6. أضف اختبار Feature أو Unit. 7. شغّل الاختبارات والتحليل والتنسيق والبناء. 8. حدّث هذا الملف عند إضافة وحدة أو Endpoint رئيسي. --- هذا الملف يصف الحالة الحالية للمشروع. يجب تحديثه مع أي تغييرات معمارية أو تشغيلية أو تغييرات على الـAPI.