# بناء الموقع التعريفي (Landing Site) لمشروع جديد

> **الغرض:** هذا المشروع (`base`) يأتي بموقع تعريفي كامل وجاهز ومُدار من لوحة التحكم.
> هذا الملف هو دليل تشغيل (playbook) يُتبع في بداية كل مشروع جديد **لإعادة تلوين ومحتوى**
> نفس الموقع التعريفي بحيث يعكس هوية التطبيق الجديد — بدون إعادة بنائه من الصفر.
>
> **يُنفَّذ تلقائياً ضمن START (الخطوة 3 — أول ما يُبنى، قبل الـ schema/DB/الخطط)** — غيّر **الألوان والمحتوى معاً** (مش واحد بس)، وما تسيبش أي لون/نص من الـ base كما هو.
>
> **قبل البدء:** املأ [`brand-identity.md`](./brand-identity.md) وضع أصول المشروع (الشعار/الـ screenshots/التحليل
> الفني/رابط Figma) في `docs/project-init/assets/`. كل خطوات هذا الدليل تقرأ منه.

---

## 0) كيف يعمل الموقع التعريفي في `base` (المعمارية)

| الطبقة | المسار |
|------|--------|
| الراوتس | `routes/web.php` → `/` (`landing.index`)، `/privacy`، `/terms`، `/lang/{lang}` تحت middleware `site.locale` |
| الكنترولر | `app/Http/Controllers/LandingController.php` (يرجّع الـ view فقط) |
| الـ Views | `resources/views/landing/index.blade.php` + `partials/` (head, header, hero, stats, about, how-it-works, download, footer, lang-switch, phone-mockup, about-illustration) |
| الصفحات القانونية | `resources/views/landing/page.blade.php` + `App\Services\PageService` (privacy/terms من جدول pages) |
| **مصدر المحتوى** | الـ helper `landing_content()` → `App\Services\LandingContentService` |
| محرر المحتوى (أدمن) | `/admin/landing` → `App\Http\Controllers\Admin\LandingContentController` |
| التنسيق (CSS) | `public/landing/css/landing.css` (متغيّرات `--safe-*`) |
| الـ JS | `public/landing/js/landing.js` |
| الصور | `public/landing/img/` |
| النصوص الافتراضية | `lang/ar/landing.php` و `lang/en/landing.php` |
| اللغة | `SetSiteLocale` middleware + session key `site-lang` + helpers `siteLang()`/`siteDirection()` |

### ترتيب أولوية المحتوى (مهم جدًا)
لكل حقل، يُحسم المحتوى بهذا الترتيب داخل `LandingContentService`:
1. **قيمة من لوحة التحكم** مخزّنة في جدول `settings` تحت مفتاح `landing.<key>` (الثنائية اللغة تُخزَّن JSON: `{"ar":"...","en":"..."}`).
2. **ملفات الترجمة** `lang/{ar,en}/landing.php`.
3. **القيم الافتراضية المدمجة** (للقوائم المتكررة: stats / features / steps) داخل `LandingContentService::default*()`.

> النتيجة: الموقع يعمل ويظهر بشكل كامل **قبل** إدخال أي بيانات في لوحة التحكم. لذلك التخصيص له مسارَان:
> **(أ)** تعديل الملفات (ألوان/نصوص افتراضية) — يصير هو الأساس لكل المشاريع المبنية على هذا التطبيق.
> **(ب)** التعديل من `/admin/landing` — يكتب فوق الملفات لكل بيئة على حدة.
> للمشروع الجديد نستخدم المسار (أ) لتثبيت الهوية، ويبقى (ب) متاحًا للعميل لاحقًا.

> ⚠️ **تنبيه (precedence gotcha):** لو قاعدة البيانات منسوخة من مشروع سابق وفيها صفوف `landing.*` قديمة في جدول `settings`، فهي ستطغى على نصوص الـ lang الجديدة ولن تظهر الهوية الجديدة. امسحها أولًا (**non-interactive** — لا تفتح tinker تفاعلي):
> ```bash
> php artisan tinker --execute="\App\Models\Setting::where('key','like','landing.%')->delete(); cache()->forget('settings');"
> # أو ببساطة بعد نسخ DB قديمة: php artisan optimize:clear
> ```

---

## 1) الألوان — أعِد تلوين الـ theme

> **الألوان تُؤخذ من التصميم (Figma) نفسه — مش مشتقّة من اللوجو.** استخرج palette المشروع من شاشات التصميم.

عدّل كتلة `:root` في `public/landing/css/landing.css` بقيم palette من [`brand-identity.md`](./brand-identity.md):

```css
:root {
  --safe-primary:      <#__>;   /* اللون الأساسي للعلامة */
  --safe-primary-600:  <#__>;   /* hover */
  --safe-primary-700:  <#__>;   /* نصوص/أيقونات على فاتح */
  --safe-primary-100:  <#__>;   /* خلفيات ناعمة */
  --safe-primary-050:  <#__>;   /* أفتح خلفية */
  --safe-accent:       <#__>;   /* لون مكمّل */
  --safe-accent-700:   <#__>;
  --safe-ink:          <#__>;   /* عناوين */
  --safe-body:         <#__>;   /* فقرات */
  --safe-muted:        <#__>;   /* نص خافت */
  --safe-surface:      #ffffff; /* كروت */
  --safe-bg:           <#__>;   /* خلفية الصفحة */
  --safe-shadow-brand: 0 14px 40px rgba(<r,g,b of primary>, 0.3);
}
```

- حدّث أيضًا `--safe-shadow-brand` و `--safe-border` بحيث تشتق من اللون الأساسي.
- ابحث في `LandingContentService` عن ألوان مكتوبة يدويًا داخل أيقونات الـ SVG الافتراضية (مثل `stroke="#3f9a78"`) واستبدلها باللون الأساسي الجديد، أو استخدم `currentColor`.

---

## 2) الخطوط

إن تطلّبت الهوية خطوطًا مختلفة:
1. في `resources/views/landing/partials/head.blade.php` بدّل روابط Google Fonts.
2. في `landing.css` حدّث `--safe-font` (و `html[lang="en"] --safe-font` للإنجليزية).

---

## 3) الشعار والصور

1. الشعار الحالي هو **`public/landing/img/logo.svg`** (wordmark بسيط افتراضي). استبدله بشعار المشروع — **دوّر عليه في `assets/` أولاً، ولو مش موجود هاته من التصميم (Figma)**:
   - الأسهل: احفظ شعار المشروع بنفس الاسم `logo.svg` فوق القديم.
   - الشعار مُشار إليه في 4 أماكن: `partials/header.blade.php`، `partials/footer.blade.php`، `partials/head.blade.php` (favicon + og:image)، وكقيمة افتراضية في `LandingContentService` (`meta.logo` / `meta.og_image`). لو غيّرت الامتداد (مثلاً إلى `.png`) حدّث المراجع الأربعة (وفي head غيّر `type="image/svg+xml"`).
2. استبدل/أضِف الأيقونات المساعدة في `public/landing/img/` إن لزم (`icon-phone.png`, `icon-card.png`).
3. **الـ Phone mockup (mockup متحرّك بـ CSS خالص):** `partials/phone-mockup.blade.php` = **reel بيلفّ تلقائياً على 4 شاشات archetypes** (رئيسية/داشبورد · إضافة/نموذج · تفاصيل + سجل نشاط · تقارير + رسم بياني) مع bottom-nav highlight بيتحرّك مع الشاشة النشطة. ألوانه من متغيّرات `--safe-*` تلقائياً.
   - **خصّصه للمشروع:** عدّل نصوص الشاشات عبر مفاتيح `mock_*` في `lang/{ar,en}/landing.php` (`mock_total`, `mock_kpi1..3`, `mock_row1/2`, `mock_add_title`, `mock_field1..3`, `mock_step1..3`, `mock_reports`, `mock_nav1..5`, …)، وبدّل الـ 4 frames في الـ blade لتحاكي **شاشات تطبيقك الحقيقية** (نفس الـ archetypes أو غيّرها).
   - أو استبدله بـ screenshots حقيقية من `assets/` لو متوفّرة.
4. **رسمة الـ about:** `partials/about-illustration.blade.php` رسمة SVG عامة — عدّلها أو استبدلها بصورة من التطبيق.

---

## 4) المحتوى النصّي

كل نصوص الموقع مفاتيح في `lang/ar/landing.php` و `lang/en/landing.php`. حدّثها لتعكس التطبيق:

- **meta:** `meta_title`, `meta_description`
- **nav:** `nav_about`, `nav_how`, `nav_download`, `nav_cta`
- **hero:** `hero_eyebrow`, `hero_title_html` (يدعم HTML للجزء الملوّن), `hero_subtitle`, `hero_cta_primary`, `hero_cta_secondary`, `hero_trust`
- **about:** `about_eyebrow`, `about_title`, `about_description` + بطاقات الميزات `feature_*_title`/`feature_*_desc`
- **how:** `how_eyebrow`, `how_title` + الخطوات `how_step*_title`/`how_step*_desc`
- **download:** `download_title`, `download_subtitle`, روابط المتجرين
- **footer:** `footer_*`
- **stats:** `stats_*`
- **mock:** `mock_*` (نصوص الـ phone mockup)

> حافِظ على نفس المفاتيح في الملفّين (ar/en). أي مفتاح ناقص يظهر كنص المفتاح نفسه.

### القوائم المتكررة (stats / features / steps)
القيم الافتراضية معرّفة برمجيًا في `LandingContentService`:
- `defaultStats()` — الأرقام والإحصائيات (value, suffix, decimals, label, icon SVG).
- `defaultFeatures()` — بطاقات «عن التطبيق».
- `defaultSteps()` — خطوات «كيف يعمل».

عدّل هذه الدوال لتطابق التطبيق الجديد (العدد، الأيقونات، والمفاتيح في lang). أو اتركها وأدخل القيم النهائية من `/admin/landing`.

---

## 5) روابط المتجرين والصفحات القانونية

- روابط App Store / Google Play: من `/admin/landing` (قسم التحميل) أو بإدخال إعدادات `landing.app_store_url` / `landing.google_play_url`.
- صفحات privacy / terms تُقرأ من جدول `pages` (slug = `privacy` / `terms`). أنشئها من أدمن الصفحات؛ إن لم توجد يعرض الموقع عنوانًا فارغًا دون كسر الروابط.

---

## 6) محرر لوحة التحكم (للعميل)

`/admin/landing` يتيح تعديل كل ما سبق بصريًا (تبويبات لكل قسم + repeaters للـ stats/features/steps + رفع صور + CKEditor للحقول الغنية). يُحفظ في جدول `settings` تحت مفاتيح `landing.*` ويُحدِّث الكاش تلقائيًا. ظهوره في السايدبار مُعرَّف في `config/sidebar_routes.php` (المفتاح `landing`).

---

## 7) التحقق (Verification)

بعد التخصيص، تأكّد من:

```
GET /            → 200 ويعرض الهوية الجديدة (شعار، ألوان، محتوى)
GET /lang/ar     → 302 ثم الصفحة بالعربية (RTL)
GET /lang/en     → 302 ثم الصفحة بالإنجليزية (LTR)
GET /privacy     → 200
GET /terms       → 200
```

- افحص الاستجابة (responsive) على موبايل/تابلت/ديسكتوب.
- افحص RTL/LTR (الاتجاه يتبدّل مع اللغة عبر `siteDirection()`).
- شغّل `php artisan optimize:clear` بعد أي تعديل على config/routes.

---

## ملخّص نقاط التخصيص (Checklist)

- [ ] `public/landing/css/landing.css` — متغيّرات `--safe-*` (الألوان) + الظلال + الخط
- [ ] `partials/head.blade.php` — خطوط Google Fonts
- [ ] `public/landing/img/logo.svg` (+ أيقونات/صور) — الشعار والأصول (مُشار إليه في header/footer/head + LandingContentService)
- [ ] `partials/phone-mockup.blade.php` + `about-illustration.blade.php` — visuals التطبيق
- [ ] `lang/{ar,en}/landing.php` — كل النصوص
- [ ] `LandingContentService::default{Stats,Features,Steps}()` — القوائم المتكررة
- [ ] روابط المتجرين + صفحات privacy/terms
- [ ] التحقق من `/`، اللغتين، والصفحات القانونية