From 35744258a19d0225e9488551cb33ca714af82763 Mon Sep 17 00:00:00 2001 From: Mohamed-Abdelhalim2 Date: Fri, 29 May 2026 01:31:23 +0000 Subject: [PATCH] =?UTF-8?q?=D8=AE=D8=B1=D9=8A=D8=B7=D8=A9=20=D9=88=D9=82?= =?UTF-8?q?=D9=88=D8=A7=D8=B9=D8=AF=20=D8=A8=D9=8A=D8=A7=D9=86=D8=A7=D8=AA?= =?UTF-8?q?=20=D8=A7=D9=84=D8=AA=D8=B7=D8=A8=D9=8A=D9=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit عمل خريطة شاملة لطريقة تعاملنا مع المشروع Signed-off-by: Mohamed-Abdelhalim2 --- .../00-architecture.md | 432 ++++++++++++++++++ 1 file changed, 432 insertions(+) create mode 100644 Project Implementation Documents/00-architecture.md diff --git a/Project Implementation Documents/00-architecture.md b/Project Implementation Documents/00-architecture.md new file mode 100644 index 0000000..12fb5f4 --- /dev/null +++ b/Project Implementation Documents/00-architecture.md @@ -0,0 +1,432 @@ +# 🌙 تطبيق "أثر" — الخطة المعمارية الكاملة + +> تطبيق محتوى قصير هادف، مستوحى من تجربة TikTok لكن بهدف نافع: محتوى ديني وتذكير يومي يترك أثرًا بدل ما يسرق العمر. + +--- + +## 📌 جدول المحتويات +1. [نصيحة المنصة](#1-نصيحة-المنصة) +2. [الهيكل العام للنظام](#2-الهيكل-العام-للنظام) +3. [التقنيات (Tech Stack)](#3-التقنيات-tech-stack) +4. [قاعدة البيانات (Database Schema)](#4-قاعدة-البيانات-database-schema) +5. [الـ APIs والتكاملات](#5-الـ-apis-والتكاملات) +6. [شاشات التطبيق (User Flow)](#6-شاشات-التطبيق-user-flow) +7. [نظام الإدارة (Admin Panel)](#7-نظام-الإدارة-admin-panel) +8. [الجوانب القانونية مع YouTube](#8-الجوانب-القانونية-مع-youtube) +9. [خطة التنفيذ المرحلية](#9-خطة-التنفيذ-المرحلية) +10. [التكلفة التقديرية](#10-التكلفة-التقديرية) + +--- + +## 1. نصيحة المنصة + +**ابدأ بـ Web App أولاً (PWA)** ثم انتقل للموبايل. الأسباب: + +| السبب | التفصيل | +|------|---------| +| 🚀 سرعة الإطلاق | تبني نسخة واحدة وتجربها مع مستخدمين حقيقيين خلال أسابيع | +| 💰 توفير التكلفة | مفيش رسوم Apple Developer ($99/سنة) ولا Google Play ($25 مرة واحدة) في البداية | +| 🛡️ تجنب الرفض | متاجر التطبيقات صارمة جدًا مع التطبيقات اللي محتواها من YouTube | +| 📱 PWA قوي | المستخدم يقدر "يثبت" الموقع على شاشته زي التطبيق العادي | +| 🔄 تحديثات فورية | متحتاجش تنتظر موافقة المتجر على كل تحديث | + +**بعد ما تثبت الفكرة وتجمع 1000+ مستخدم نشط**، نعمل نسخة React Native للموبايل (نفس الكود يشتغل Android + iOS). + +--- + +## 2. الهيكل العام للنظام + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 👤 المستخدم (Browser/App) │ +└────────────────────────┬────────────────────────────────────┘ + │ + ┌────────────▼────────────┐ + │ Frontend (Next.js) │ + │ • Feed عمودي swipe │ + │ • YouTube IFrame Player│ + │ • أزرار تفاعل │ + │ • أذكار / مواقيت صلاة │ + └────────────┬────────────┘ + │ + ┌────────────────┼────────────────┐ + │ │ │ +┌───────▼──────┐ ┌───────▼──────┐ ┌──────▼───────┐ +│ Supabase │ │ YouTube APIs │ │ External APIs│ +│ (Backend) │ │ │ │ │ +│ │ │ • IFrame │ │ • Aladhan │ +│ • PostgreSQL │ │ • Data API v3│ │ (مواقيت) │ +│ • Auth │ │ │ │ • أذكار JSON │ +│ • Storage │ │ │ │ │ +│ • Realtime │ │ │ │ │ +└──────────────┘ └──────────────┘ └──────────────┘ + ▲ + │ +┌───────┴────────┐ +│ Admin Panel │ ← إنت/المشرفين تختاروا الفيديوهات +│ (Next.js) │ +└────────────────┘ +``` + +--- + +## 3. التقنيات (Tech Stack) + +### الواجهة الأمامية (Frontend) +- **Next.js 14** (React + SSR) — يدعم PWA بسهولة +- **TailwindCSS** — تصميم سريع ومريح +- **Framer Motion** — انتقالات سلسة بين الفيديوهات (swipe up/down) +- **react-youtube** — مكتبة جاهزة لتضمين IFrame Player + +### الخادم (Backend) — كله في Supabase +- **PostgreSQL** — قاعدة بيانات قوية +- **Supabase Auth** — تسجيل دخول (Google, Email, Anonymous) +- **Row Level Security (RLS)** — أمان على مستوى الصف +- **Edge Functions** — لو محتاج منطق سيرفر مخصص +- **Realtime** — التعليقات تظهر فورًا + +### خدمات خارجية +- **YouTube IFrame Player API** — لتشغيل الفيديوهات (مجاني، بدون حدود) +- **YouTube Data API v3** — لجلب بيانات الفيديو تلقائيًا (10k طلب/يوم مجانًا) +- **Aladhan API** — مواقيت الصلاة (مجاني) +- **Vercel** — استضافة الـ Frontend (مجاني للبداية) + +### أدوات إضافية +- **OneSignal** — Push notifications مجانية (للتذكير اليومي) +- **PostHog / Plausible** — تحليلات تحترم الخصوصية + +--- + +## 4. قاعدة البيانات (Database Schema) + +```sql +-- 👤 جدول المستخدمين (مدار من Supabase Auth) +users ( + id uuid PRIMARY KEY, + email text, + display_name text, + avatar_url text, + created_at timestamp, + -- إعدادات شخصية + daily_goal_minutes int DEFAULT 10, + notification_time time, + city text -- لمواقيت الصلاة +) + +-- 🎥 جدول الفيديوهات (إنت تضيفها يدويًا أو من Admin Panel) +videos ( + id uuid PRIMARY KEY, + youtube_id text UNIQUE NOT NULL, -- مثلاً: dQw4w9WgXcQ + title text, + description text, + duration_seconds int, + channel_name text, + channel_id text, + thumbnail_url text, + category text, -- 'قرآن' / 'حديث' / 'سيرة' / 'تزكية' + tags text[], + scholar_name text, -- اسم الشيخ/الداعية + is_approved boolean DEFAULT false, -- المشرف يوافق قبل النشر + added_by uuid REFERENCES users(id), + created_at timestamp, + -- إحصائيات داخلية (مش من يوتيوب) + views_count int DEFAULT 0, + likes_count int DEFAULT 0, + saves_count int DEFAULT 0 +) + +-- ❤️ إعجابات (محلية في تطبيقك) +likes ( + user_id uuid REFERENCES users(id), + video_id uuid REFERENCES videos(id), + created_at timestamp, + PRIMARY KEY (user_id, video_id) +) + +-- 🔖 محفوظات +saves ( + user_id uuid REFERENCES users(id), + video_id uuid REFERENCES videos(id), + collection text DEFAULT 'default', -- مجموعات: 'للمراجعة' / 'مفضلة' + created_at timestamp, + PRIMARY KEY (user_id, video_id) +) + +-- 💬 تعليقات (محلية في تطبيقك) +comments ( + id uuid PRIMARY KEY, + user_id uuid REFERENCES users(id), + video_id uuid REFERENCES videos(id), + content text, + parent_id uuid REFERENCES comments(id), -- للردود + is_hidden boolean DEFAULT false, -- للإشراف + created_at timestamp +) + +-- 📊 سجل المشاهدات (لمعرفة الفيديوهات اللي شافها المستخدم) +watch_history ( + user_id uuid REFERENCES users(id), + video_id uuid REFERENCES videos(id), + watched_seconds int, + completed boolean, + watched_at timestamp, + PRIMARY KEY (user_id, video_id, watched_at) +) + +-- 📿 الأذكار اليومية +daily_remembrance ( + id uuid PRIMARY KEY, + category text, -- 'صباح' / 'مساء' / 'نوم' / 'استيقاظ' + arabic text, + translit text, + meaning text, + source text, + count int DEFAULT 1 +) + +-- 🎯 الرحلات التعليمية (Playlists منظمة) +journeys ( + id uuid PRIMARY KEY, + title text, -- "رحلة في السيرة النبوية" + description text, + cover_url text, + video_ids uuid[], -- مرتبة بالترتيب + difficulty text, -- 'مبتدئ' / 'متوسط' / 'متقدم' + estimated_minutes int +) + +-- 📈 تتبع تقدم الرحلات +journey_progress ( + user_id uuid REFERENCES users(id), + journey_id uuid REFERENCES journeys(id), + completed_video_ids uuid[], + started_at timestamp, + completed_at timestamp, + PRIMARY KEY (user_id, journey_id) +) +``` + +--- + +## 5. الـ APIs والتكاملات + +### 🎥 YouTube IFrame Player API (الأهم) + +**ده اللي بيعرض الفيديو جوه تطبيقك.** + +```javascript +// مثال بسيط: عرض فيديو يوتيوب بشكل عمودي +import YouTube from 'react-youtube'; + +function VideoPlayer({ youtubeId, onEnd }) { + const opts = { + height: '100%', + width: '100%', + playerVars: { + autoplay: 1, + controls: 0, // إخفاء أزرار يوتيوب + modestbranding: 1, // تقليل علامة يوتيوب + rel: 0, // عدم اقتراح فيديوهات أخرى + playsinline: 1, + }, + }; + + return ( + + ); +} +``` + +**ملاحظات مهمة:** +- ✅ مجاني تمامًا، بدون حد طلبات +- ✅ المشاهدات تتحسب لصاحب الفيديو (عدل) +- ⚠️ لازم يظهر زر "YouTube" صغير (شرط من جوجل) +- ⚠️ ما تقدرش تخفي الإعلانات لو الفيديو فيه إعلانات + +### 📊 YouTube Data API v3 (اختياري لكن مفيد) + +لجلب بيانات الفيديو تلقائيًا (لما تضيف فيديو جديد): +``` +GET https://www.googleapis.com/youtube/v3/videos + ?part=snippet,contentDetails,statistics + &id=VIDEO_ID + &key=YOUR_API_KEY +``` + +### 🕌 Aladhan API — مواقيت الصلاة +``` +GET https://api.aladhan.com/v1/timingsByCity + ?city=Cairo&country=Egypt&method=5 +``` + +### 🔔 OneSignal — إشعارات +- إشعار يومي: "وقت أذكار الصباح 🌅" +- إشعار قبل الصلاة بـ 10 دقائق +- إشعار للفيديو الأسبوعي الجديد + +--- + +## 6. شاشات التطبيق (User Flow) + +``` +1. 🚪 شاشة الترحيب + ↓ +2. 🔐 تسجيل دخول (Google / Email / Skip كضيف) + ↓ +3. 🎯 اختيار الاهتمامات (قرآن / تزكية / سيرة / فقه...) + ↓ +4. 🏠 الشاشة الرئيسية — Vertical Feed + ┌─────────────────────────┐ + │ │ + │ 🎥 فيديو يلعب │ + │ تلقائيًا │ + │ │ + │ [اسم الشيخ] ❤️ 245 │ + │ [العنوان] 💬 12 │ + │ [#تزكية] 🔖 │ + │ 📤 │ + └─────────────────────────┘ + ↑ swipe up = التالي + ↓ swipe down = السابق + ↓ +5. 📿 تبويبات سفلية: + [🏠 الرئيسية] [🛤️ رحلات] [📿 أذكار] [🔖 محفوظاتي] [👤 ملفي] +``` + +### الشاشات التفصيلية: + +| الشاشة | الوصف | +|--------|------| +| 🏠 **Feed الرئيسي** | فيديوهات عمودية، swipe للتنقل، autoplay | +| 🛤️ **الرحلات** | سلاسل منظمة (مثال: "10 أيام في رياض الصالحين") | +| 📿 **الأذكار** | أذكار الصباح/المساء بشكل تفاعلي مع عداد | +| 🕌 **مواقيت الصلاة** | حسب موقع المستخدم + تذكيرات | +| 🔖 **محفوظاتي** | الفيديوهات اللي حفظها المستخدم | +| 👤 **ملفي الشخصي** | إحصائيات وقت المشاهدة، الرحلات المكتملة، إعدادات | +| ⚙️ **الإعدادات** | الوضع المريح للعين، حد يومي للمشاهدة، إشعارات | + +### 🌙 ميزات "ضد الإدمان" (مهمة جدًا) +- **حد يومي**: المستخدم يحدد 10/20/30 دقيقة، التطبيق يقفل بعدها +- **رسالة بعد كل 5 فيديوهات**: "خد نفس، اشرب مياه، صلِّ على النبي ﷺ" +- **بدون عداد متابعين/لايكات مبالغ فيه**: علشان مفيش "سباق شهرة" +- **بدون scroll لا نهائي ليلًا**: بعد الـ 11م يظهر تذكير بالنوم + +--- + +## 7. نظام الإدارة (Admin Panel) + +لوحة بسيطة عشان إنت (أو فريقك) تضيفوا/تراجعوا المحتوى: + +### الصفحات: +1. **➕ إضافة فيديو** — لصق رابط يوتيوب، البيانات تتجلب تلقائيًا، تختار التصنيف، وافق +2. **📋 قائمة الفيديوهات** — بحث، فلترة، حذف، تعديل +3. **🛤️ إدارة الرحلات** — إنشاء سلاسل من فيديوهات موجودة +4. **💬 إشراف التعليقات** — مراجعة وإخفاء التعليقات غير المناسبة +5. **👥 المستخدمون** — إحصائيات، حظر إذا لزم +6. **📊 لوحة التحليلات** — الفيديوهات الأكثر مشاهدة، أوقات الذروة، إلخ + +--- + +## 8. الجوانب القانونية مع YouTube + +### ✅ ما هو مسموح (شروط الخدمة): +- استخدام **IFrame Player API** لتضمين الفيديوهات +- بناء واجهة مخصصة حول المُشغّل +- جمع إعجابات/تعليقات على تطبيقك (منفصلة عن يوتيوب) +- اقتراح فيديوهات للمستخدمين + +### ❌ ما هو ممنوع: +- تحميل الفيديو وإعادة استضافته +- إخفاء علامة يوتيوب تمامًا +- تعطيل الإعلانات +- استخدام طرق غير رسمية (yt-dlp, scraping) + +### 📋 شروط لازم تلتزم بيها: +1. **اربط بـ ToS و Privacy** الخاصين بيوتيوب +2. **خلي زر "Watch on YouTube" ظاهر** +3. **متغيرش/متعدلش الفيديو نفسه** +4. **احترم حقوق الناشرين** (لو ناشر طلب إزالة فيديوه، شيله) + +📖 المرجع الرسمي: [YouTube API Services Terms of Service](https://developers.google.com/youtube/terms/api-services-terms-of-service) + +--- + +## 9. خطة التنفيذ المرحلية + +### 🥇 المرحلة 1 — MVP (4-6 أسابيع) +- [ ] إعداد Next.js + Supabase + Tailwind +- [ ] تصميم شاشة الفيديو العمودي مع swipe +- [ ] تكامل YouTube IFrame +- [ ] تسجيل دخول (Google + Anonymous) +- [ ] إعجاب + حفظ +- [ ] Admin Panel بسيط لإضافة 30-50 فيديو مختار بعناية +- [ ] نشر كـ PWA على Vercel + +### 🥈 المرحلة 2 — تفعيل المجتمع (4 أسابيع) +- [ ] التعليقات + الردود +- [ ] الإشعارات (OneSignal) +- [ ] أذكار الصباح/المساء +- [ ] مواقيت الصلاة +- [ ] حد يومي للمشاهدة + رسائل التذكير + +### 🥉 المرحلة 3 — الرحلات والنمو (6 أسابيع) +- [ ] نظام الرحلات (Journeys) +- [ ] تتبع التقدم والشارات +- [ ] مشاركة الفيديوهات على واتساب/تويتر +- [ ] تحسين خوارزمية الاقتراحات + +### 🏆 المرحلة 4 — تطبيقات الموبايل (8 أسابيع) +- [ ] React Native (نفس الـ Backend) +- [ ] نشر على Google Play +- [ ] نشر على App Store +- [ ] Deep Linking + +--- + +## 10. التكلفة التقديرية + +### في البداية (أول 1000 مستخدم) — **مجاني تقريبًا** 🎉 +| الخدمة | التكلفة | +|--------|---------| +| Vercel (Hosting) | $0 | +| Supabase (Free tier) | $0 | +| YouTube APIs | $0 | +| Aladhan API | $0 | +| OneSignal | $0 | +| Domain (.com) | ~$12/سنة | +| **الإجمالي** | **~$1/شهر** | + +### بعد النمو (10,000+ مستخدم نشط) +| الخدمة | التكلفة | +|--------|---------| +| Vercel Pro | $20/شهر | +| Supabase Pro | $25/شهر | +| OneSignal Growth | $9/شهر | +| **الإجمالي** | **~$54/شهر** | + +### لو حبيت تطبيقات موبايل: +- Apple Developer: $99/سنة +- Google Play: $25 (مرة واحدة) + +--- + +## 🌟 خلاصة + +إنت معاك فكرة قوية، والتنفيذ التقني فيها **ممكن جدًا** ومش معقد. الأهم من الكود هو: + +1. **اختيار المحتوى بعناية** — أنت أو لجنة شرعية تختار قنوات موثوقة +2. **التصميم اللي يحترم وقت المستخدم** — مش يدمنه +3. **بناء مجتمع نواة** — 100 مستخدم متفاعل خير من 10,000 خامل + +--- + +## 🚀 الخطوة التالية + +تحب نبدأ نبني الـ **Prototype** فعليًا؟ أقدر أعمل: +- صفحة HTML/JS شغّالة تعرض فيديو يوتيوب بشكل عمودي زي تيكتوك +- مع أزرار إعجاب وحفظ (تشتغل بـ localStorage في البداية) +- قول لي وابدأ.