system-prompts-and-models-of-ai-tools/dealix/docs/PLATFORM_SERVICES_STRATEGY.md

Platform Services Strategy — برج التحكم بالنمو

(Dealix Growth Control Tower)

الهدف: تحويل Dealix من "WhatsApp Growth Operator" إلى منصة نمو متعددة القنوات تشتغل تحت سقف واحد، بسياسات أمان موحدة، ومسار اعتماد واحد، وبروتوكول أحداث موحد.

---

1. لماذا Platform Services؟

كل قناة (WhatsApp, Gmail, Calendar, LinkedIn, X, Instagram, GBP, Sheets, CRM, Moyasar, Website Forms) تحتاج:

• تطبيع الإشارات (signal normalization).
• سياسة قبول/رفض موحدة (PDPL-aware).
• حل هوية متقاطع (cross-channel identity).
• مدخل تنفيذي موحد (single tool gateway) لمنع الإرسال البارد، تسريب الأسرار، أو الدفع بدون تأكيد.
• صندوق بريد موحد (unified inbox) ببطاقات قابلة للاعتماد.
• سجل أفعال (action ledger) للمراجعة (SDAIA / PDPL).
• سجل أثر (proof ledger) لتسويق "كم وفّرنا، كم سحبنا، كم منعنا من مخاطر".

بدون هذه الطبقة، كل ميزة جديدة تحتاج تكامل مخصص → فوضى أمنية + أمنية + قانونية.

---

2. الوحدات (10 modules)

#	الوحدة	الدور
1	event_bus	تصنيف موحد لـ27 نوع حدث (whatsapp/email/calendar/lead/payment/review/social/partner/sheet/crm/action).
2	identity_resolution	دمج phone + email + CRM ID + social handles → هوية موحدة.
3	channel_registry	11 قناة، لكل واحدة capabilities + allowed/blocked actions + PDPL notes.
4	action_policy	محرك قواعد (block_cold_whatsapp, block_payment_no_confirm, block_secrets, external_send_needs_approval...).
5	tool_gateway	المخرج التنفيذي الوحيد. كل أداة تمر من هنا → سياسة → draft / approval_required / blocked / ready.
6	unified_inbox	بطاقات قرار (≤3 أزرار، عربية، type+risk+recommended_action).
7	action_ledger	سجل كل فعل بمراحله (requested → approved → executed).
8	proof_ledger	عدّاد أثر (leads, meetings, drafts, sends, payments, revenue, risks_blocked, time_saved).
9	service_catalog	12 خدمة قابلة للبيع تحت Dealix Operator OS.
10	(router + tests)	api/routers/platform_services.py + اختبارات شاملة.

---

3. القنوات الـ11

whatsapp, gmail, google_calendar, moyasar, linkedin_lead_forms,
x_api, instagram_graph, google_business_profile, google_sheets,
crm, website_forms

كل قناة لها:

• capabilities
• beta_status (live / beta / coming_soon)
• allowed_actions / blocked_actions
• risk_level
• notes_ar

مثال: WhatsApp يحظر cold_send_without_consent. Gmail يستخدم gmail.compose فقط (drafts). Calendar live_inserted=False حتى يربط OAuth.

---

4. سياسة الأمان (Action Policy)

قواعد block أساسية:

1. WhatsApp بارد بدون consent → blocked (PDPL).
2. أي charge/refund بدون user_confirmed=true → blocked.
3. أي payload يحوي api_key/secret/token/... → blocked.

قواعد approval_required:

• أي إرسال خارجي (send_*) → اعتماد إنساني.
• إدراج موعد في تقويم → اعتماد.
• DM على سوشل → اعتماد + opt-in.
• صفقة قيمتها ≥ 200,000 ريال → اعتماد.

default: allow (للـ read-only data ops).

---

5. Tool Gateway

كل أداة (whatsapp.send_message, gmail.compose, calendar.insert_event, moyasar.refund, gbp.reply_review, ...) يجب تمر من invoke_tool().

النتائج المحتملة:

• unsupported — أداة غير مسجلة.
• blocked — السياسة منعت.
• approval_required — تحتاج قبول إنساني.
• draft_created — افتراضياً (live env flag = OFF).
• ready_for_adapter — جاهز للتنفيذ الحقيقي إذا اشتغل live env flag.

Live env flags (افتراضياً كلها OFF):

WHATSAPP_ALLOW_LIVE_SEND
GMAIL_ALLOW_LIVE_SEND
CALENDAR_ALLOW_LIVE_INSERT
MOYASAR_ALLOW_LIVE_CHARGE
GBP_ALLOW_LIVE_REPLY

---

6. صندوق البريد الموحد (Unified Inbox)

8 أنواع بطاقات:

opportunity, email_lead, whatsapp_reply, payment,
meeting_prep, review_response, partner_suggestion, action_required

كل بطاقة:

• ≤3 أزرار (تطبيق قيد WhatsApp Reply Buttons).
• عربية (title_ar, summary_ar, why_it_matters_ar, recommended_action_ar).
• risk_level (low/medium/high).

البطاقات تُبنى تلقائياً من PlatformEvent عبر build_card_from_event().

---

7. Proof Ledger

عدّاد يقيس الأثر العملي للمنصة:

leads_created, meetings_booked, drafts_approved,
messages_sent, payments_initiated, payments_paid,
revenue_influenced_sar, risks_blocked, time_saved_hours,
partner_opportunities, by_channel

هذا هو Marketing Asset — لتُري العميل: "في 30 يوم، نحن ساعدناك تعمل X، منعنا Y مخاطر، وفرنا Z ساعة".

---

8. خدمات قابلة للبيع (Service Catalog)

12 خدمة تجارية:

1. growth_operator_subscription — اشتراك شهري للمنصة.
2. channel_setup_service — ربط القنوات (one-time).
3. lead_intelligence_service — إثراء + تأهيل لقاءات.
4. outreach_approval_service — drafts + approval workflow.
5. partnership_sprint — فرص تعاون عبر Partner Graph.
6. email_revenue_rescue — استعادة عملاء إيميل.
7. social_growth_os — تنبيهات + drafts + جدولة.
8. local_business_growth — GBP + reviews + visibility.
9. ai_visibility_aeo_sprint — Answer Engine Optimization.
10. revenue_proof_pack_service — تقرير أثر لمستثمرين / عملاء.
11. customer_success_operator — خفض churn + توسيع.
12. payments_collections_operator — تذكير + تحصيل (Moyasar).

---

9. Endpoints (/api/v1/platform/...)

GET  /services/catalog
GET  /channels
GET  /channels/{channel_key}
GET  /policy/rules
POST /actions/evaluate
POST /actions/approve
GET  /ledger/summary
POST /events/ingest
GET  /inbox/feed
POST /identity/resolve
GET  /identity/resolve-demo
POST /tools/invoke
GET  /proof-ledger/demo

---

10. اختبارات

tests/unit/test_platform_services.py — تغطية لكل الوحدات الـ10:

• catalog completeness
• channel coverage + cold-send blocked
• event validation
• policy (cold WA blocked, secrets blocked, payment confirmation, external send approval, high-value review)
• gateway (unsupported / blocked / draft default / live flag check)
• identity multi-signal merge
• inbox card validation (≤3 buttons + valid type)
• action ledger summary
• proof ledger structure

---

11. ما لا تفعله هذه الطبقة

• لا ترسل واتساب فعلياً (افتراضياً draft).
• لا ترسل Gmail فعلياً.
• لا تدرج موعد في Google Calendar.
• لا تأخذ أو تعيد دفعة بدون user_confirmed.
• لا تخزن مفاتيح API في payload.

---

12. ما يلي

• ربط Adapters حقيقية (WhatsApp Cloud, Gmail, Calendar) خلف الـenv flags.
• استبدال in-memory ledgers بـ Supabase.
• تشغيل proof_ledger على بيانات إنتاج مع تجربة عميل واحد.