# تقرير المرحلة 0 — الجرد والتشخيص

> تقرير فقط، بدون أي تعديل على الكود. لا يبدأ أي تنفيذ قبل موافقتك.
> التاريخ: 2026-07-14

---

## خلاصة سريعة

البنية التقنية والـ backend سليمة فعلاً كما ذكرت — لا تحتاج إعادة كتابة. المشاكل الحقيقية في طبقتين:

1. **طبقة العرض/التجربة (UI/UX):** الصفحة الرئيسية والـ views الثلاثة تشترك في مظهر واحد رتيب (كروت ناعمة على سطح رمادي)، وأهم عيب أن **البورتفوليو بلا صور** في الصفحة الرئيسية وصفحة قائمة الأعمال — وهذا قاتل لموقع مصمم.
2. **الوثائق:** الملفات الأساسية دقيقة، لكن ملفات `frontend-system-*.md` الثلاثة قديمة (تشير إلى مسارات محذوفة).

كما رصدت تعقيدات على طراز الـ SaaS زائدة عن حاجة موقع شخصي، أهمها: نظام الـ Toast، بنية الأدمن الثلاثية، حماية نموذج التواصل (rate-limit + Turnstile)، وطبقتا مصادقة للأدمن.

---

## 0.2 — حالة الوثائق (`docs/` و `specs/`) مقابل الكود

### دقيقة ومطابقة للكود ✅

| الملف | الحالة |
|---|---|
| `docs/ARCHITECTURE.md` | دقيق (ملاحظة: يسمّي الملف `middleware` لكنه فعلياً `proxy.ts` بعد ترقية Next.js 16) |
| `docs/DOMAIN_RULES.md` | دقيق — قواعد البورتفوليو والميديا والتواصل كلها مطابقة للـ schema |
| `docs/PROJECT_OVERVIEW.md` | دقيق (ينقصه ذكر بعض المسارات) |
| `docs/FEATURES.md` | دقيق لكنه ناقص (لا يذكر الاختبارات الموجودة فعلاً ولا نظام الصوت) |
| كل ملفات `specs/*.md` السبعة | دقيقة وصادقة في التمييز بين المنفَّذ والمقترح |

### قديمة أو خاطئة ❌ (تحتاج تصحيح في المرحلة 1)

الملفات الثلاثة `docs/frontend-system-audit.md`، `frontend-system-current-state.md`، `frontend-system-refactor-summary.md` كُتبت قبل إعادة تسمية مجلد، فصارت تشير إلى مسارات غير موجودة:

- `components/root/*` ← الصحيح `components/admin/*`
- `lib/root-navigation.ts` ← الصحيح `lib/admin-navigation.ts`
- تدّعي وجود مجلد `src/` — وهو غير موجود أصلاً

المحتوى المفاهيمي فيها (التوكنز، الحركة، الأيقونات) ما زال صحيحاً؛ المشكلة في المسارات فقط.

### ميزات موجودة في الكود لكنها غير موثّقة

- نظام الصوت: `components/sound-provider.tsx` + `sound-toggle.tsx`
- مسارات API: `app/api/health` و `app/api/site/default-locale`
- خط رفع/تقديم الميديا المحلي: `app/uploads/media/[...segments]/route.ts`
- صفحة `portfolio/category` الفهرسية، وصفحات إعدادات الموقع الفرعية (brand / localization)

---

## 0.3 و 0.4 — الـ Views الثلاثة والصفحة الرئيسية

المقصود بـ «3 views» على الأرجح قوالب الصفحات الرئيسية الثلاثة:

### View 1 — الصفحة الرئيسية (`app/[locale]/(site)/page.tsx`)

**البنية:** hero بطول الشاشة (نص + تدرّج لوني فقط) ← ثم 6 أقسام متتالية (Bento، Marquee، Projects، Capabilities، Process، Contact CTA) كلها مبنية على نفس نمط `SectionHeading` + شبكة كروت `AppCard` متطابقة.

**لماذا ضعيفة:**

- **لا مفهوم ولا صور إطلاقاً** — الـ hero نص وتدرّج فقط، ولا توجد أي صورة عمل في الصفحة كلها. حتى كروت المشاريع المميزة نصية بلا صور مصغّرة.
- **رتابة وتكرار** — خمسة من ستة أقسام نفس النمط البصري تماماً، لا إيقاع ولا تمييز بينها.
- **تسلسل هرمي ضعيف** — بعد hero طويل يصطدم النظر بجدار كروت متساوية الوزن، ولا شيء يقول «هذا الأهم». الـ CTA الوحيد مدفون في الأسفل.
- **محتوى عام** («Core stack»، «Current focus») يشبه صفحة «about» أكثر من واجهة مصمم.

### View 2 — قائمة الأعمال (`portfolio/page.tsx`)

hero مضغوط + فلتر تصنيفات + شبكة `PortfolioProjectGrid` بعمودين. صفحة التصنيف `category/[slug]` مطابقة حرفياً لها.

**لماذا ضعيفة:**

- **بلا صور بتاتاً** — الكروت 100% نص رغم أن البيانات تحتوي `coverImagePath`. هذه أكبر مشكلة: القائمة التي يُفترض أن تبيع العمل لا تعرض منه شيئاً. يشبه فهرس مدوّنة لا بورتفوليو.
- تخطيط مسطّح بعمودين، كروت متساوية، بلا تمييز أو معاينة عند المرور.

### View 3 — تفاصيل المشروع (`portfolio/[slug]/page.tsx`)

`PageHero` **فارغ** (بلا عنوان) ثم `PortfolioProjectDetail` الذي يتفرّع لثلاثة قوالب: `GRID` / `STORY` / `CASE_STUDY`.

**لماذا ضعيفة:**

- **hero فارغ** يهدر أعلى الصفحة بمساحة تدرّج فارغة؛ العنوان الحقيقي يظهر لاحقاً داخل كرت.
- **كل شيء محبوس داخل كروت** — الصور والنصوص والمعرض كلها في كروت مدوّرة على سطح، بلا صورة غلاف ممتدة (full-bleed) ولا عرض غامر. الصور مقصوصة بارتفاعات ثابتة.
- **ثلاثة قوالب بمظهر واحد** — رغم تعقيد الكود، النتيجة البصرية متشابهة.

### حالة المعرض (Gallery)

يوجد معرض فعلاً لكن **داخل صفحة التفاصيل فقط** (`AssetGallery`). لا يوجد أي معرض/صور في الصفحة الرئيسية ولا في قائمة الأعمال — وهذا هو أساس ملاحظتك «لا يوجد gallery».

### النظام البصري الحالي

- ألوان: متغيرات HSL بثيم فاتح/داكن، لون العلامة أحمر-برتقالي `9 73° 50%`.
- زوايا: مدوّرة وناعمة جداً (`radius-surface: 24px`) — تعزّز مظهر الكروت الموحّد.
- خطوط: `Museo Sans Rounded` (لاتيني) + `Dubai` (عربي).
- **العيب على مستوى النظام:** كفؤ تقنياً لكنه يُنتج نسيجاً واحداً في كل مكان (كرت ناعم على سطح رمادي + لمسة برتقالية) — يشبه ثيم لوحة تحكم SaaS طُبِّق على بورتفوليو، لا هوية بصرية مبنية للبورتفوليو أولاً.

---

## 0.5 — نظام الـ Toast/الإشعارات (جاهز للإزالة)

المكتبة: `react-hot-toast` (لا Radix toast ولا Sonner).

**البنية الأساسية (مرشحة للحذف):**

- `lib/toast.tsx` — الغلاف حول react-hot-toast
- `components/ui/toaster.tsx` — مضيف العرض الوحيد
- `components/admin/query-toast-bridge.tsx` — يقرأ `?success=`/`?error=` و sessionStorage ويطلق الـ toast ثم ينظّف الرابط
- نقطة التركيب: `app/layout.tsx` (سطور 6، 9، 99-100)
- التبعية: `react-hot-toast` في `package.json`

**مواضع الاستدعاء:** toggle الثيم والصوت، تبديل اللغة، easter egg للنقر الثلاثي على الشعار، وكل أوامر الأدمن (media, site-settings, portfolio, smtp, marquee, maintenance) عبر `?success=`/`?error=`، ونموذج التواصل.

**⚠️ تحذير مهم — الـ toast هو قناة التغذية الراجعة الوحيدة في:**

1. **كل عمليات الأدمن (CRUD)** — الحفظ/الحذف/الخطأ تظهر فقط عبر الـ toast. إزالته دون بديل تترك كل عملية بلا أي تأكيد أو رسالة خطأ.
2. **أخطاء دخول الأدمن** (`locked`/`invalid`) — تصبح صامتة.
3. **أخطاء نموذج التواصل** (تحقق، rate-limit، Turnstile) — تعتمد كلياً على الـ toast.

**الخلاصة:** إزالة الـ toast من العناصر التجميلية (toggles، easter egg) آمنة تماماً. أما أوامر الأدمن ونموذج التواصل فتحتاج **بديلاً بسيطاً للتغذية الراجعة** (رسالة inline داخل الصفحة) قبل الإزالة، وإلا ستصبح العمليات صامتة. النجاح في نموذج التواصل محمي لأنه يحوّل لصفحة `/success` مستقلة.

---

## 0.6 — تعقيدات SaaS زائدة (مقترحة للإزالة، بالأولوية)

اسم المشروع نفسه `sass-mohfarawati` يكشف الأصل: بُني كأنه منتج SaaS متعدد المستخدمين، بينما هو موقع شخصي بمالك واحد.

| # | البند | لماذا زائد | خطر الإزالة |
|---|---|---|---|
| P1 | **بنية الأدمن الثلاثية** (`_admin` + `admin-internal` + `/root`) — نحو 19 ملف re-export + منطق توجيه في `lib/admin-routing.ts` و`proxy.ts` | موقع بمالك واحد يحتاج مسار أدمن واحد خلف كلمة مرور، لا توجيه بمستوى white-label | متوسط |
| P2 | **الإعدادات في قاعدة البيانات** (`AppConfig` + `lib/app-config.ts` 310 سطر) تخزّن كل شيء: إعدادات، SMTP، maintenance، عدّادات rate-limit، قفل الدخول | معظمها ثابت ويصلح كمتغيرات بيئة/ملف إعداد بدل لوحة تحكم | متوسط |
| P3 | **حماية نموذج التواصل** (`contact-guard.ts` + `contact-protection.ts` + شاشة أدمن): rate-limit لكل IP + Turnstile | دفاع ضد الإساءة لنموذج عالي الحركة؛ بورتفوليو شخصي يكفيه `zod` + honeypot | منخفض |
| P4 | **قفل دخول الأدمن ضد التخمين** (`admin-auth.ts` 309 سطر) + طبقة Basic Auth ثانية في `proxy.ts` | طبقتا مصادقة لمستخدم واحد؛ كوكي موقّع واحد يكفي | متوسط |
| P5 | **مواصفات ميزات SaaS ميتة**: `specs/orders.md`, `products.md`, `downloads.md`, `project-inquiry.md` | مجرد وثائق لميزات تجارية غير مبنية أصلاً | منخفض (حذف وثائق) |
| P6 | **مكتبة ميديا مع تتبّع الاستخدام** (`MediaAsset` + `MediaUsage` polymorphic + 4 وحدات lib) | ميزة CMS للفرق؛ المالك الواحد يربط الصور مباشرة بالمشاريع | **مرتفع** (مربوطة بالبورتفوليو والإعدادات) |
| P7 | **ثيم/ماركي قابلان للتعديل وقت التشغيل** (`site-theme.ts`, `marquee-settings.ts` + شاشات أدمن) | تخصيص للعميل؛ المالك يثبّت لونه ونصوصه في الكود | متوسط |
| P8 | **Docker/Postgres + طلب middleware ذاتي** (`proxy.ts` يستدعي `/api/site/default-locale` على نفسه في كل طلب) | ثقيل لبورتفوليو؛ الـ self-fetch نمط مضاد نتج عن P2 | متوسط-مرتفع |

**نقطة إيجابية:** لا توجد جداول Order/Product/Download/Analytics/AuditLog/User-roles في قاعدة البيانات — هذه بقيت مواصفات فقط (P5). النماذج الأساسية (`Category`, `PortfolioProject`, `PortfolioSection`, `PortfolioAsset`) شرعية وسليمة.

**ترتيب مقترح للإزالة (من الأسهل):** P5 (حذف وثائق) → P3 → Toast → P1 → P4 → P2/P8 → لاحقاً الأعلى خطراً P6/P7.

---

## القرارات المطلوبة منك قبل بدء المرحلة 1

المرحلة 0 اكتملت. لن أعدّل أي شيء قبل موافقتك. أحتاج قرارك في:

1. **نظام Toast:** الإزالة متفق عليها. هل تريدني أستبدله برسائل inline بسيطة داخل صفحات الأدمن والتواصل (موصى به لتفادي عمليات صامتة)، أم إزالة تامة بلا بديل؟
2. **تعقيدات SaaS (P1–P8):** أيها توافق على إزالته الآن؟ اقتراحي أن نبدأ بالآمن (P5, P3, P8-self-fetch) ونؤجل الأعلى خطراً (P6 مكتبة الميديا، P1 بنية الأدمن) لجلسة منفصلة.
3. **تصحيح الوثائق القديمة** (`frontend-system-*.md`): موافقة على تحديث المسارات؟