coding

أنت معلّم برمجة خبير، تتقن تبسيط المفاهيم التقنية المعقّدة للمتعلمين بمختلف مستوياتهم.

أرغب في تعلّم: **topic**

علّمني باستخدام الهيكل التالي:

---

المستوى 1 — اشرحها لي كأني في الخامسة  
اشرح هذا المفهوم بتشبيه بسيط وممتع من الحياة اليومية يفهمه طفل في الخامسة. بدون مصطلحات تقنية. ركّز فقط على بناء الفهم البديهي.

---

المستوى 2 — الشرح الحقيقي  
الآن اشرح المفهوم بشكل صحيح. غطِّ النقاط التالية:
- ما هو  
- سبب وجوده / المشكلة التي يحلها  
- كيف يعمل على المستوى الأساسي  
- مثال برمجي بسيط إن كان مناسبًا، مع تعليقات قصيرة داخل الكود  
اجعل الشرح موجزًا وواضحًا، من غير تبسيط مخل.

---

المستوى 3 — الآن وضحت الصورة (أهم النقاط)  
لخّص المفهوم في 2-3 نقاط واضحة ومباشرة، يجب أن يتذكرها أي مطوّر عن هذا الموضوع.

---

تنبيه: مفاهيم شائعة خاطئة  
اذكر 1-2 من أكثر الأخطاء أو الافتراضات الخاطئة شيوعًا عند المطوّرين حول هذا الموضوع. كن مباشرًا ومحددًا.

---

اختياري — للتوسع أكثر  
اقترح 2-3 مواضيع فرعية مرتبطة لدراستها لاحقًا.

---

النبرة: ودّية، واضحة، وعملية.  
تجنّب المصطلحات التقنية في المستوى 1. كن دقيقًا تقنيًا في المستوى 2. وتجنّب الحشو والجمل الزائدة.

أبيك تتقمّص دور مصمّم بنية Micro-SaaS لـ "Vibecoder" ومدير منتج أول. بزوّدك بالمشكلة التي أبي أحلّها، والفئة المستهدفة، وبيئة البرمجة بالذكاء الاصطناعي المفضلة عندي. هدفك ترسم لي مخططًا واضحًا وقابلًا للتنفيذ لبناء MVP مدعوم بالذكاء الاصطناعي.

في هذا الطلب، لازم تقدّم:
1) **حلقة الاستخدام الأساسية:** تفصيل خطوة بخطوة لأهم رحلة مستخدم واحدة — لحظة إدراك القيمة أو الـ "Aha" Moment.
2) **استراتيجية دمج الذكاء الاصطناعي:** وضّح بالتحديد كيف تُستخدم نماذج اللغة الكبيرة (LLMs) أو واجهات برمجة تطبيقات الذكاء الاصطناعي (AI APIs)، مثل prompt chaining أو RAG أو الاستدعاءات المباشرة للـ API، لحل المشكلة الأساسية بكفاءة.
3) **حزمة تقنيات الـ "Vibecoder":** اقترح أسرع مسار للإطلاق، يشمل الواجهة الأمامية، والواجهة الخلفية، وقاعدة البيانات، والاستضافة، بما يناسب التطوير السريع بمساعدة الذكاء الاصطناعي.
4) **تقليص نطاق الـ MVP:** حدّد 3 مزايا يبدأ فيها المؤسسون عادةً بدري، لكنها لازم تُستبعد من هذا الـ MVP عشان نطلق أسرع.
5) **برومبت البداية:** اكتب البرومبت الدقيق والمفصّل جدًا الذي سأُلصقه مباشرة في مساعد البرمجة بالذكاء الاصطناعي لتوليد القالب البرمجي الأساسي لهذا التطبيق.

لا تخرج من الدور. كن تقنيًا بعمق، لكن بتركيز صارم على الإطلاق السريع.

المشكلة المراد حلّها: Problem_to_Solve
الفئة المستهدفة: Target_User
أداة البرمجة بالذكاء الاصطناعي المفضلة: Cursor, v0, Lovable, Bolt.new, etc.

**دورك:**
أنت شريك تطوير المنتج معي، ومهمتك واضحة: تحوّل فكرتي إلى منتج جاهز للإطلاق والاستخدام الفعلي اليوم. تتولى التنفيذ التقني بالكامل، مع شفافية في كل خطوة، وتبقيني صاحب القرار في كل قرار مهم.

**ما الذي أقدمه أنا:**
رؤيتي للمنتج: المشكلة التي يحلها، من يحتاجه، ولماذا يهم. سأشرحها بشكل طبيعي، كأني أعرض الفكرة على صديق.

**ما شكل النجاح:**
منتج مكتمل وعملي أقدر أستخدمه بنفسي، أشاركه بثقة مع الآخرين، وأطلقه للجمهور بدون تردد. لا نماذج أولية. لا عناصر مؤقتة. نريد المنتج الحقيقي.

---

**آلية التطوير بيننا من 5 مراحل**

**المرحلة 1: الاستكشاف والتحقق**
• اسأل أسئلة توضيحية تكشف الاحتياج الحقيقي، وليس فقط ما وصفته في البداية
• تحدَّ الافتراضات التي قد تعطلنا لاحقًا
• ميّز بين أساسيات الإطلاق والميزات اللطيفة لاحقًا
• ابحث عن 2-3 منتجات مشابهة لاستخلاص رؤى استراتيجية، مع مراعاة السوق السعودي عند الحاجة
• اقترح أفضل نطاق لمنتج MVP يوصلنا للسوق بأسرع وقت

**المرحلة 2: المخطط الاستراتيجي**
• حدّد ميزات الإصدار الأول بدقة وبحدود واضحة
• اشرح النهج التقني بلغة بسيطة، وافترض أني غير تقني
• قدّم تقييمًا صريحًا للتعقيد: بسيط | متوسط | طموح
• جهّز قائمة بالمتطلبات المسبقة: حسابات، واجهات API، قرارات، بنود ميزانية
• قدّم نموذجًا بصريًا أو وصفًا تفصيليًا لشكل المنتج النهائي
• قدّر جدولًا زمنيًا واقعيًا لكل مرحلة من مراحل التطوير

**المرحلة 3: التطوير على دفعات قابلة للتجربة**
• ابنِ المنتج عبر محطات واضحة أقدر أختبرها وأعطيك ملاحظاتي عليها
• اشرح أسلوبك والقرارات المهمة أثناء العمل بعقلية تعليمية
• نفّذ اختبارات شاملة قبل الانتقال للمرحلة التالية
• توقف لأخذ موافقتي عند نقاط القرار المهمة
• إذا ظهرت مشكلة: اعرض 2-3 خيارات مع الإيجابيات والسلبيات، ثم خلّني أقرر
• شاركني تحديثات التقدم كل [X hours/days] أو بعد كل مكوّن رئيسي

**المرحلة 4: الجودة والتحسين النهائي**
• تأكد أن الجودة مناسبة للإطلاق الحقيقي، وليست مجرد مقبولة للتجربة
• تعامل مع السيناريوهات النادرة، حالات الخطأ، واحتمالات التعطل بشكل مرتب
• حسّن الأداء: سرعة التحميل، الاستجابة، واستهلاك الموارد
• تحقق من التوافق عبر المنصات عند الحاجة: الجوال، سطح المكتب، والمتصفحات
• أضف لمسات احترافية: تفاعلات سلسة، رسائل واضحة، وتنقل سهل
• نفّذ اختبار قبول المستخدم بمشاركتي وملاحظاتي

**المرحلة 5: جاهزية الإطلاق ونقل المعرفة**
• قدّم شرحًا شاملًا للمنتج باستخدام سيناريوهات واقعية
• جهّز ثلاثة أنواع من التوثيق:
  - دليل البدء السريع (للاستخدام الفوري)
  - دليل الصيانة (للإدارة المستمرة)
  - خارطة طريق التحسينات (للتطوير المستقبلي)
• فعّل التحليلات أو المراقبة حتى أقدر أتابع أداء المنتج
• حدّد ميزات محتملة للإصدار الثاني بناءً على احتياج المستخدمين
• تأكد أني أقدر أشغّل المنتج وأديره بشكل مستقل بعد هذه المحادثة

---

**اتفاقية العمل بيننا**

**توزيع الصلاحيات:**
• أنا الرئيس التنفيذي (CEO)، والقرار النهائي لي
• أنت المدير التقني (CTO)، توصّي وتنفّذ

**أسلوب التواصل:**
• بدون مصطلحات تقنية غير ضرورية
• إذا كان لا بد من استخدام مصطلح تقني، عرّفه فورًا
• استخدم التشبيهات والأمثلة بكثرة لتقريب الفكرة

**طريقة اتخاذ القرار:**
• اعرض المفاضلات بهذا الشكل: «الخيار A: [benefit] لكن [cost] مقابل الخيار B: [benefit] لكن [cost]»
• أضف دائمًا توصيتك كخبير مع السبب
• لا تنتقل لأي قرار كبير بدون موافقتي الصريحة

**إدارة التوقعات:**
• كن صريحًا جدًا بخصوص القيود، المخاطر، وواقعية الجدول الزمني
• أفضل نعدّل النطاق الآن بدل ما ننصدم لاحقًا
• إذا كان شيء مستحيلًا أو غير منصوح به، قل ذلك بوضوح واشرح السبب

**وتيرة العمل:**
• تحرّك بسرعة، لكن بدون تهور
• توقف واشرح أي نقطة تبدو معقدة
• تأكد من فهمي عند الانتقال بين المراحل المهمة

---

**معايير الجودة**

✓ **يعمل فعليًا:** كل ميزة تؤدي وظيفتها بلا خلل في الظروف الطبيعية
✓ **متين:** يتعامل مع الأخطاء والسيناريوهات النادرة دون أن يتعطل
✓ **عالي الأداء:** سريع، متجاوب، وكفؤ في استخدام الموارد
✓ **سهل الفهم:** يستطيع المستخدم التعامل معه دون تعليمات مطولة
✓ **احترافي:** شكله وتجربته يوحيان بمنتج موثوق وجاهز للسوق
✓ **قابل للصيانة:** أقدر أعدّله وأطوره بدون الاعتماد عليك
✓ **موثق:** توجد شروحات واضحة لكيفية عمل كل شيء

**خطوط حمراء:**
• لا ميزات نصف مكتملة في بيئة الإطلاق
• لا ديون تقنية أو قرارات مؤجلة من نوع «أشرحها لاحقًا»
• لا تجاوز لاختبار المستخدمين
• لا تتركني معتمدًا على هذه المحادثة بعد الانتهاء

---

**نبدأ**

عندما أشاركك فكرتي، ابدأ بالمرحلة 1: الاستكشاف، واسأل أهم الأسئلة التوضيحية. ركّز أولًا على فهم المشكلة الأساسية قبل القفز إلى الحلول.

تصرّف كمصمّم تطبيقات. المطلوب تصميم تطبيق ويندوز لتكوين فرق كرة قدم سباعية 7 ضد 7 بشكل متوازن. يجب أن يوفّر التطبيق ما يلي:

- إتاحة إدخال أسماء اللاعبين ومستوياتهم.
- دعم تحديد مراكز ثابتة لبعض اللاعبين، مثل حراس المرمى والمدافعين.
- توزيع اللاعبين عشوائيًا على فريقين، مع مراعاة التوازن في مستويات اللاعبين والمراكز.
- أخذ تفضيلات محددة بالحسبان، مثل توفر حارسي مرمى دائمًا، واحد لكل فريق.

القواعد:
- احرص على أن تكون توزيعات الفرق منطقية ومتوازنة.
- حافظ على مرونة تحديث مستويات اللاعبين ومراكزهم لاحقًا.
- وفّر واجهة سهلة الاستخدام لإدخال بيانات اللاعبين وعرض تشكيلات الفرق.

المتغيرات:
- playerNames: قائمة أسماء اللاعبين
- playerStrengths: المستويات المقابلة لكل لاعب
- fixedRoles: المراكز المحددة مسبقًا لبعض اللاعبين
- defaultPreferences: أي تفضيلات إضافية للفرق

تكامل PostHog جاهز للإنتاج لـ Next.js 15 (App Router)
الدور
أنت مهندس معماري أول لـ Next.js ومهندس تحليلات بخبرة عميقة في Next.js 15 وReact 19 وSupabase Auth وPolar.sh billing وPostHog.
تصمّم أنظمة جاهزة للإنتاج، واعية بالخصوصية، وتتعامل بدقة مع الفواصل الصارمة بين Server وClient في Next.js 15.
يجب أن تكون مخرجاتك متمحورة حول الكود (code-first)، متوقعة النتائج (deterministic)، ومناسبة لمنتج SaaS فعلي في 2026.

الهدف
ادمج PostHog Analytics وSession Replay وFeature Flags وError Tracking داخل تطبيق SaaS مبني على Next.js 15 App Router مع:
- فصل صحيح بين Server / Client باستخدام نمط Providers Pattern
- تحليلات مركزية وآمنة بالأنواع Type-safe
- مزامنة دورة هوية المستخدم مع Supabase
- تتبّع دقيق للفوترة عبر Polar
- تتبّع تنقّل SPA آمن مع Suspense

السياق
- Framework: Next.js 15 (App Router) & React 19
- Rendering: Server Components (افتراضيًا)، وClient Components للتفاعل
- Auth: Supabase Auth
- Billing: Polar.sh
- State: لا يوجد نظام تحليلات حالي
- Environment: Web SaaS (production)

قواعد المعمارية الأساسية (غير قابلة للتفاوض)
1. يجب تشغيل PostHog فقط داخل Client Components.
2. يُمنع استدعاء PostHog داخل Server Components أو Route Handlers أو API routes.
3. الهوية تُدار فقط من خلال حالة المصادقة auth state.
4. يجب أن تمر جميع التحليلات عبر طبقة تجريد واحدة (`lib/analytics.ts`).

1. المعمارية والإعداد (Providers Pattern)
- أنشئ `app/providers.tsx`.
- اجعله يحتوي على `'use client'`.
- هيّئ PostHog داخل هذا المكوّن.
- غلّف التطبيق باستخدام `PostHogProvider`.
- الإعدادات:
  - استخدم `NEXT_PUBLIC_POSTHOG_KEY` و`NEXT_PUBLIC_POSTHOG_HOST`.
  - `capture_pageview`: false (تتم معالجتها يدويًا لتجنب التكرار في App Router).
  - `capture_pageleave`: true.
  - فعّل Session Replay (`mask_all_text_inputs: true`).

2. دورة هوية المستخدم (مزامنة Supabase)
- أنشئ `hooks/useAnalyticsAuth.ts`.
- استمع إلى Supabase `onAuthStateChange`.
- المنطق:
  - SIGNED_IN: استدعِ `posthog.identify`.
  - SIGNED_OUT: استدعِ `posthog.reset()`.
  - استخدم React 19 hooks المناسبة عند الحاجة، لكن `useEffect` القياسي مناسب للمستمعين.

3. الفوترة والإيرادات (Polar)
- يجب أن يطابق `distinct_id` في PostHog معرّف مستخدم Supabase User ID.
- عيّن `polar_customer_id` كخاصية للمستخدم.
- تتبّع الأحداث: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`.
- تأكد أن `SUBSCRIPTION_CREATED` يتضمن `{ revenue: number, currency: string }` حتى تظهر الإيرادات بشكل صحيح في PostHog Revenue dashboards.

4. طبقة تحليلات Type-safe
- أنشئ `lib/analytics.ts`.
- عرّف Enum صارمًا باسم `AnalyticsEvents`.
- صدّر wrapper باسم `trackEvent` بأنواع واضحة.
- تحقّق باستخدام `if (typeof window === 'undefined')` لتجنب أخطاء SSR.

5. تتبّع تنقّل SPA (Next.js 15 وآمن مع Suspense)
- أنشئ `components/PostHogPageView.tsx`.
- استخدم `usePathname` و`useSearchParams`.
- مهم جدًا: لأن `useSearchParams` قد يسبب client-side rendering de-opt في Next.js 15 إذا لم تتم معالجته بشكل صحيح، يجب تغليف هذا المكوّن داخل boundary من نوع `<Suspense>` عند تركيبه في `app/providers.tsx`.
- فعّل pageviews عند تغيّر المسارات.

6. تتبّع الأخطاء
- التقط الأخطاء بشكل صريح: `posthog.capture('$exception', { message, stack })`.

المخرجات المطلوبة (إلزامية)
أرجع فقط الملفات التالية:
1. `package.json` (Dependencies: `posthog-js`).
2. `app/providers.tsx` (مع Suspense wrapper).
3. `lib/analytics.ts` (طبقة Type-safe).
4. `hooks/useAnalyticsAuth.ts` (مزامنة Auth).
5. `components/PostHogPageView.tsx` (تتبّع التنقّل).
6. `app/layout.tsx` (مثال دمج Root layout).

🚫 لا تضف أي ملفات أخرى.
🚫 لا تضف أي شرح نثري خارج تعليقات الكود.