Files

T

CI / quality (push) Waiting to run

Details

refactor: drop toast + over-engineered extras, add inline admin feedback

Phase 1 cleanup of the personal-site revamp. Backend/architecture untouched;
changes are limited to removing unused complexity and restoring feedback.

Removals
- Toast system: delete react-hot-toast, Toaster, QueryToastBridge, lib/toast,
  the toggle/easter-egg calls, related i18n keys and the dependency.
- Contact protection: remove Turnstile + per-IP rate limiting
  (lib/contact-guard, lib/contact-protection, admin screen, form widget,
  app-config wiring, nav entry, test).
- Speculative specs: delete orders, products, downloads, project-inquiry.

Inline feedback (replaces toast, no new deps)
- Add lib/admin-feedback (withFlash/readFlash) and components/admin/admin-flash,
  rendered centrally by AdminDashboardShell.
- Emit success/error messages for media, site-settings, portfolio, smtp,
  marquee and maintenance actions; pages read them via searchParams.
- Contact form shows validation/delivery errors inline; success still
  redirects to /success.

Docs
- Fix stale paths in frontend-system-* (components/root -> components/admin,
  lib/root-navigation -> lib/admin-navigation, drop phantom src/) and remove
  contact-protection references from docs and CLAUDE.md.
- Add docs/PHASE0_DIAGNOSIS.md (diagnosis report).

Note: proxy.ts self-fetch kept intentionally; it also drives maintenance mode.

2026-07-14 21:03:51 +02:00

13 KiB

Raw Blame History

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

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

خلاصة سريعة

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

طبقة العرض/التجربة (UI/UX): الصفحة الرئيسية والـ views الثلاثة تشترك في مظهر واحد رتيب (كروت ناعمة على سطح رمادي)، وأهم عيب أن البورتفوليو بلا صور في الصفحة الرئيسية وصفحة قائمة الأعمال — وهذا قاتل لموقع مصمم.
الوثائق: الملفات الأساسية دقيقة، لكن ملفات 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 هو قناة التغذية الراجعة الوحيدة في:

كل عمليات الأدمن (CRUD) — الحفظ/الحذف/الخطأ تظهر فقط عبر الـ toast. إزالته دون بديل تترك كل عملية بلا أي تأكيد أو رسالة خطأ.
أخطاء دخول الأدمن (locked/invalid) — تصبح صامتة.
أخطاء نموذج التواصل (تحقق، 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 اكتملت. لن أعدّل أي شيء قبل موافقتك. أحتاج قرارك في:

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

13 KiB Raw Blame History Unescape Escape

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

خلاصة سريعة

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

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

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

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

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

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

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

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

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

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

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

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

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

13 KiB

Raw Blame History

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

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

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

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