مُضاعِف / Modaafa Ads AI

منصة SaaS عربية لإدارة حسابات Google Ads: تسجيل دخول، ربط كل الحسابات التي يملك المستخدم صلاحية عليها، تبديل الحساب المحدد، مزامنة الحملات، فحص الحساب، مساعد ذكي، توصيات تمر عبر مركز موافقات، تقارير، وفوترة Stripe.

سياسة التنفيذ

• لا تُسحب مؤشرات الأداء من حساب MCC نفسه.
• مهام التحسين المجدولة تنشئ توصيات فقط.
• أي تغيير حي يطلب موافقة المستخدم، ثم يجري فحصاً مسبقاً وتحققاً من القيمة الحالية وحدود الأمان.
• كل تنفيذ ناجح يسجل بيانات التراجع عندما يدعم الإجراء ذلك.

التقنية

• Next.js 15 وReact 18 وTypeScript
• Supabase Auth/Postgres/RLS
• Google Ads API وGoogle OAuth
• Anthropic API للمساعد والتحليل
• Stripe Billing للاشتراكات والتجربة
• Vercel للاستضافة والمهام المجدولة
• Resend لتنبيهات التشغيل

التشغيل المحلي

المتطلبات: Node.js 20+ وpnpm 11.9.

pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm dev

يفتح التطبيق افتراضياً على http://localhost:3000.

الفحص الكامل

pnpm check

يشغل فحص الأنواع، ESLint، الاختبارات، ثم بناء الإنتاج. ويجري GitHub Actions الفحص نفسه على main وطلبات الدمج.

قاعدة البيانات

لبيئة جديدة، طبّق db/schema.sql أولاً من Supabase SQL Editor. بعد ذلك تطبق التحديثات المتتابعة من db/migrations/.

للتحديثات اللاحقة يمكن استخدام:

SUPABASE_DB_URL='postgresql://...' pnpm db:migrate

الأداة تحتاج psql، تحفظ أسماء الملفات المطبقة في _modaafa_migrations، ولا تطبع رابط قاعدة البيانات.

مسارات الإنتاج المهمة

• / الصفحة العامة
• /login الدخول
• /onboarding الإعداد الأول
• /dashboard لوحة التحكم
• /assistant المساعد
• /audit فحص الحساب
• /optimizer مركز الموافقات
• /campaigns الحملات
• /reports التقارير
• /billing الاشتراك والفوترة
• /settings الإعدادات وحذف الحساب
• /privacy و/terms و/data-deletion الصفحات القانونية
• /api/health فحص عام محدود، وفحص مفصل عند إرسال CRON_SECRET كـ Bearer token

النشر

استخدم قائمة الإطلاق ودليل التشغيل. وجود المتغيرات لا يعني أن التكامل يعمل؛ الفحص المفصل يتحقق أيضاً من قاعدة البيانات وStripe وAnthropic والبريد والمهام المجدولة.

حالة الإطلاق

لا يوصف الإصدار بأنه جاهز تجارياً حتى:

1. تنجح pnpm check.
2. تطبق كل migrations على Supabase الإنتاج.
3. يرجع فحص الصحة المفصل launch_ready: true.
4. توافق Google على OAuth للتطبيق العام، ويضبط GOOGLE_OAUTH_APP_VERIFIED=true بعد الموافقة الفعلية فقط.
5. تمر تجربة مستخدم جديدة كاملة وتجربة اشتراك حقيقية منخفضة المخاطر ثم إلغاؤها.

لا تحفظ أسراراً في Git، ولا تضف ملفات .env إلى المستودع.