diff --git a/salesflow-saas/docs/FULL_NEXT_STEP_AND_STACK_EXPANSION_AR.md b/salesflow-saas/docs/FULL_NEXT_STEP_AND_STACK_EXPANSION_AR.md new file mode 100644 index 00000000..69242665 --- /dev/null +++ b/salesflow-saas/docs/FULL_NEXT_STEP_AND_STACK_EXPANSION_AR.md @@ -0,0 +1,213 @@ +# خطة التنفيذ الكاملة — ما بعد الإغلاق + +> **الهدف**: تحويل النظام من "مغلق نظرياً" إلى "مثبت تشغيلياً وقابل للبيع" +> **القاعدة**: لا تبيع إلا ما يشتغل. لا تدّعي إلا ما هو حي. + +--- + +## البوابات الثمانية — معيار "كل شيء تمام" + +| # | البوابة | الحالة | +|---|---------|--------| +| 1 | **Truth** — مصدر واحد للحقيقة، لا overclaim | **PASS** | +| 2 | **Contract** — كل output حرج schema-bound | **PARTIAL** — 3/17 schemas مستخدمة (golden path) | +| 3 | **Trust** — Class B يفشل بدون correlation_id | **PASS** — مفعّل في approval_bridge | +| 4 | **Durable** — مسار واحد resumable end-to-end | **PARTIAL** — golden path حي لكن بدون persistence | +| 5 | **Executive** — Executive Room تجيب 5 أسئلة | **PASS** — weekly-pack endpoint حي | +| 6 | **Release** — CI يحرس الإطلاق | **PARTIAL** — architecture_brief في CI | +| 7 | **Saudi** — workflow حساس واحد مربوط | **TARGET** | +| 8 | **Commercial** — التسويق يطابق الواقع | **PASS** — marketer hub مع forbidden claims | + +--- + +## ما أُنجز (الوضع الحالي) + +### حي فعلاً +- Golden Path: `POST /api/v1/golden-path/run` → PartnerDossier → EconomicsModel → ApprovalPacket → EvidencePack +- Trust enforcement: Class B actions تفشل بدون correlation_id +- Auto evidence: deal close → auto evidence pack assembly +- Executive Room: weekly-pack contract → ExecWeeklyPack schema +- 9/9 frontend مربوطة بـ APIs حقيقية +- 8/8 backend APIs تقرأ من DB حقيقية +- Architecture Brief: 40/40 PASS + +### ناقص +- 14/17 structured output schemas غير مستخدمة +- Connector live health probes +- Saudi compliance live validation +- OpenTelemetry +- OIDC + attestations +- OpenFGA + +--- + +## الأدوات المطلوب إضافتها + +### أضف الآن + +| الأداة | لماذا | أين | +|--------|-------|-----| +| **OpenTelemetry** | traces + logs + metrics مترابطة | `requirements.txt` + gateway + services | +| **GitHub OIDC** | بدل long-lived secrets | `.github/workflows/` | +| **Artifact attestations** | provenance مثبت | CI build step | +| **OpenFGA** | object-level authorization | approval_bridge + evidence packs | + +### أضف قريباً + +| الأداة | لماذا | متى | +|--------|-------|-----| +| **Great Expectations** | data quality gates | قبل evidence pack assembly | +| **Unstructured** | استخراج عقود وDD docs | عند تفعيل M&A flow | +| **Airbyte** | data movement موحد | عند 5+ مصادر | + +### في الرادار + +| الأداة | لماذا | متى | +|--------|-------|-----| +| **OPA** | policy engine | عندما القواعد > 50 | +| **Temporal** | durable execution | بعد نجاح المسار الذهبي | +| **MCP expansion** | أدوات أكثر | بعد استقرار المسارات | + +--- + +## Backend — ما يجب تثبيته + +### Endpoint Inventory + +| المجموعة | عدد الـ endpoints | Classification | +|----------|------------------|---------------| +| Auth | 8 | Internal — no side effects | +| Leads | 12 | External — Class A (read) / Class B (import) | +| Deals | 10 | External — Class B (stage change triggers evidence) | +| Approvals | 6 | Critical — Class B (approve/reject) | +| Contradictions | 5 | Internal — Class A | +| Evidence Packs | 5 | Critical — Class B (assemble/review) | +| Executive Room | 5 | Internal — Class A (read-only) | +| Compliance | 5 | Internal — Class A | +| Connectors | 4 | Internal — Class A | +| Golden Path | 2 | Critical — Class B (creates approval + evidence) | +| Strategic Deals | 8 | External — Class B | +| Outreach | 6 | External — Class B (sends messages) | + +### Trust Enforcement Coverage + +| Enforcement | المُغطى | الفجوة | +|-------------|---------|--------| +| Policy gate (A/B/C) | All OpenClaw actions | Direct API calls bypass OpenClaw | +| correlation_id required | Class B via gateway | API routes don't enforce yet | +| Auto evidence on deal close | deals.py | Other entity closes not covered | +| Structured output validation | Golden path only | Other flows use free-form | + +### ما يجب فعله + +1. **كل Class B API route**: تحقق من correlation_id في payload +2. **كل outreach endpoint**: تحقق من PDPL consent قبل الإرسال +3. **كل strategic deal endpoint**: log to audit_log +4. **idempotency key**: على كل POST يسبب side effects + +--- + +## Frontend — ما يجب تثبيته + +### Surface Maturity + +| Surface | API Wired | Contract-Driven | States Complete | Arabic RTL | +|---------|-----------|-----------------|-----------------|-----------| +| Executive Room | ✅ | ✅ (weekly-pack) | Partial | ✅ | +| Approval Center | ✅ | Partial | Partial | ✅ | +| Evidence Viewer | ✅ | Partial | Partial | ✅ | +| Compliance | ✅ | Partial | Partial | ✅ | +| Connectors | ✅ | ✅ | Partial | ✅ | +| Forecast | ✅ | Partial | Partial | ✅ | +| Risk Heatmap | ✅ | Partial | Partial | ✅ | +| Violations | ✅ | Partial | Partial | ✅ | +| Partner Pipeline | ✅ | Partial | Partial | ✅ | + +### ما يجب فعله + +1. **Executive Room**: استهلك weekly-pack endpoint كمصدر وحيد +2. **كل surface**: أضف loading spinner + empty state message + error handler +3. **Demo indicator**: badge يوضح "بيانات تجريبية" vs "بيانات حية" + +--- + +## الوثائق — ما يجب إضافته + +### For Customer (العميل) + +| الوثيقة | الحالة | الأولوية | +|---------|--------|----------| +| Onboarding guide | Done (LIVE_DEPLOYMENT_GUIDE) | — | +| Admin setup guide | Target | P1 | +| Executive quickstart | Target | P1 | +| FAQ | Target | P2 | + +### For Team (الفريق) + +| الوثيقة | الحالة | +|---------|--------| +| Architecture docs | Done (26+ docs) | +| Release docs | Done (release-prep) | +| Runbooks | Done (memory/runbooks/) | +| Closure program | Done (10 tracks) | + +### For Sales (البيع) + +| الوثيقة | الحالة | +|---------|--------| +| One-pager | Done | +| Marketer Hub | Done | +| Outreach sequences | Done | +| Demo seeder | Done | +| Deployment guide | Done | +| Revenue engine plan | Done | + +--- + +## الترتيب الأمثل — 5 مراحل + +### المرحلة 1: Assurance (أسبوع 1) +- [ ] فعّل OpenTelemetry (trace_id + span_id في gateway + services) +- [ ] فعّل OIDC في CI/deploy +- [ ] أضف attestation step في CI +- [ ] اربط Release Matrix بـ PR checks + +### المرحلة 2: Live Path (أسبوع 1-2) +- [x] Golden Path حي end-to-end +- [x] Trust enforcement (correlation_id required) +- [x] Auto evidence on deal close +- [x] Executive weekly-pack contract +- [ ] Contradiction auto-detection في golden path + +### المرحلة 3: Saudi Activation (أسبوع 2-3) +- [ ] اختر workflow: مشاركة بيانات شريك +- [ ] اربطه بـ PDPL data classification +- [ ] اربطه بـ retention/export rules +- [ ] اربطه بـ audit path + AI risk overlay + +### المرحلة 4: Productization (أسبوع 3-4) +- [ ] Admin setup guide +- [ ] Executive quickstart +- [ ] Customer FAQ +- [ ] Public landing page copy +- [ ] Trust/compliance page + +### المرحلة 5: Expansion (شهر 2+) +- [ ] Procurement/vendor deal flow +- [ ] Renewal/expansion deal flow +- [ ] Deeper M&A DD orchestration +- [ ] More connectors with governance +- [ ] Broader OpenFGA coverage + +--- + +## تجنب الآن + +| ما تتجنبه | السبب | +|-----------|-------| +| Temporal قبل golden path يستقر | over-engineering | +| أكثر من 2 golden paths بنفس الوقت | تشتت | +| MCP tools expansion | agent sprawl | +| Industry pages قبل case study حقيقي | لا proof | +| SOC2 certification claim | لا نملكها | +| "أفضل من Salesforce" messaging | مختلف ≠ أفضل | diff --git a/salesflow-saas/docs/governance/endpoint-inventory.md b/salesflow-saas/docs/governance/endpoint-inventory.md new file mode 100644 index 00000000..eadda2c2 --- /dev/null +++ b/salesflow-saas/docs/governance/endpoint-inventory.md @@ -0,0 +1,100 @@ +# Endpoint Inventory — Trust Classification + +> **Parent**: [`MASTER_OPERATING_PROMPT.md`](../../MASTER_OPERATING_PROMPT.md) +> **Purpose**: Every endpoint classified by risk, side effects, and trust requirements. + +--- + +## Classification Key + +| Class | Meaning | Trust Requirements | +|-------|---------|-------------------| +| **A** | Safe auto — read-only, no side effects | None | +| **B** | Approval-gated — causes side effects or external communication | correlation_id + approval_token | +| **B+** | Critical — financial, legal, or irreversible | correlation_id + approval_token + evidence_pack | +| **C** | Forbidden — never allowed via API | Blocked unconditionally | + +--- + +## Tier-1 Governance Endpoints + +| Endpoint | Method | Class | Side Effects | Trust Enforced | +|----------|--------|-------|-------------|---------------| +| `/executive-room/snapshot` | GET | A | None | — | +| `/executive-room/weekly-pack` | GET | A | None | — | +| `/executive-room/risks` | GET | A | None | — | +| `/executive-room/decisions-pending` | GET | A | None | — | +| `/executive-room/forecast-vs-actual` | GET | A | None | — | +| `/approval-center/` | GET | A | None | — | +| `/approval-center/stats` | GET | A | None | — | +| `/approval-center/{id}/approve` | POST | **B+** | Updates approval status | correlation_id via payload | +| `/approval-center/{id}/reject` | POST | **B+** | Updates approval status | correlation_id via payload | +| `/approval-center/{id}/escalate` | POST | **B** | Escalation notification | — | +| `/contradictions/` | GET | A | None | — | +| `/contradictions/` | POST | A | Creates record | — | +| `/contradictions/stats` | GET | A | None | — | +| `/contradictions/{id}/resolve` | POST | **B** | Status update | — | +| `/evidence-packs/assemble` | POST | **B** | Creates SHA256 pack | — | +| `/evidence-packs/` | GET | A | None | — | +| `/evidence-packs/{id}/review` | PUT | **B** | Status update | — | +| `/evidence-packs/{id}/verify` | GET | A | None | — | +| `/compliance/matrix/` | GET | A | None | — | +| `/compliance/matrix/scan` | POST | A | Updates control status | — | +| `/compliance/matrix/posture` | GET | A | None | — | +| `/compliance/matrix/risk-heatmap` | GET | A | None | — | +| `/connectors/governance` | GET | A | None | — | +| `/connectors/{key}/health-check` | POST | A | Updates status | — | +| `/model-routing/dashboard` | GET | A | None | — | +| `/model-routing/health` | GET | A | None | — | +| `/model-routing/costs` | GET | A | None | — | +| `/forecast-control/unified` | GET | A | None | — | +| `/forecast-control/variance` | GET | A | None | — | +| `/forecast-control/recalibrate` | POST | **B** | Triggers AI reforecast | — | +| `/golden-path/run` | POST | **B+** | Creates approval + evidence | correlation_id generated | +| `/golden-path/dossier` | POST | A | None (generates schema) | — | + +--- + +## Core Business Endpoints + +| Endpoint | Method | Class | Side Effects | Trust Required | +|----------|--------|-------|-------------|---------------| +| `/leads` | GET | A | None | — | +| `/leads` | POST | A | Creates record | — | +| `/leads/import` | POST | **B** | Bulk create | — | +| `/deals` | GET | A | None | — | +| `/deals` | POST | A | Creates record | — | +| `/deals/{id}/stage` | PUT | **B+** | Stage change + auto evidence on close | Auto evidence on closed_won | +| `/deals/{id}` | DELETE | **B** | Soft delete | — | + +--- + +## External Communication Endpoints + +| Endpoint | Method | Class | Side Effects | Trust Required | +|----------|--------|-------|-------------|---------------| +| `/outreach/*` | POST | **B** | Sends WhatsApp/email/SMS | PDPL consent + approval_token | +| `/sequences/*` | POST | **B** | Starts multi-channel sequence | PDPL consent + approval_token | +| `/whatsapp-webhook` | POST | A | Processes inbound | Webhook verification | + +--- + +## Strategic Deal Endpoints + +| Endpoint | Method | Class | Side Effects | Trust Required | +|----------|--------|-------|-------------|---------------| +| `/strategic-deals/` | GET | A | None | — | +| `/strategic-deals/` | POST | **B** | Creates deal | — | +| `/strategic-deals/{id}/negotiate` | POST | **B+** | Negotiation action | correlation_id | +| `/strategic-deals/match` | POST | A | AI matching | — | + +--- + +## Summary + +| Class | Count | Enforcement Status | +|-------|-------|--------------------| +| A (safe auto) | ~45 | No enforcement needed | +| B (approval-gated) | ~15 | correlation_id enforced via gateway | +| B+ (critical) | ~6 | correlation_id + evidence (golden path enforced) | +| C (forbidden) | 5 | Blocked in policy.py | diff --git a/salesflow-saas/revenue-activation/deployment/ADMIN_SETUP_GUIDE.md b/salesflow-saas/revenue-activation/deployment/ADMIN_SETUP_GUIDE.md new file mode 100644 index 00000000..17f57c5f --- /dev/null +++ b/salesflow-saas/revenue-activation/deployment/ADMIN_SETUP_GUIDE.md @@ -0,0 +1,120 @@ +# دليل إعداد المشرف — Dealix Admin Setup Guide + +> **الجمهور**: مدير IT أو المسؤول التقني عند العميل +> **المدة**: 30-60 دقيقة + +--- + +## 1. إنشاء الحسابات + +### حساب المشرف (أنت) +- ادخل على `https://[your-domain]/` +- سجّل باسمك وإيميلك +- الدور: `admin` +- اللغة: `ar` (عربي) أو `en` + +### حسابات الفريق +لكل عضو في الفريق: +1. اذهب إلى **الإعدادات** → **المستخدمون** +2. أضف مستخدم جديد +3. حدد الدور: + +| الدور | الصلاحيات | +|-------|----------| +| `admin` | كل شيء — الإعدادات والمستخدمين والتقارير | +| `manager` | الموافقات + التقارير + الإدارة | +| `sales` | إدارة الصفقات والعملاء + WhatsApp | +| `viewer` | عرض فقط — لا تعديل | + +--- + +## 2. إعداد القنوات + +### WhatsApp Business +1. اذهب إلى **الإعدادات** → **القنوات** → **WhatsApp** +2. أدخل: + - WhatsApp API Token + - Phone Number ID + - Verify Token +3. اختبر بإرسال رسالة لرقمك + +### البريد الإلكتروني +1. اذهب إلى **الإعدادات** → **القنوات** → **البريد** +2. أدخل إعدادات SMTP أو SendGrid API Key +3. اختبر بإرسال بريد تجريبي + +--- + +## 3. إعداد الموافقات + +### حدود SLA +| الإعداد | القيمة الافتراضية | التوصية | +|---------|------------------|---------| +| تحذير SLA | 8 ساعات | 4-8 ساعات | +| خرق SLA | 24 ساعة | 12-24 ساعة | +| التصعيد الحرج | 2× الخرق | الافتراضي | + +### من يوافق؟ +حدد لكل نوع قرار: +- **رسائل WhatsApp**: المدير المباشر +- **خصم >10%**: مدير المبيعات +- **خصم >25%**: VP +- **شراكة جديدة**: CEO + +--- + +## 4. استيراد البيانات + +### استيراد العملاء المحتملين +1. جهز ملف CSV بالأعمدة: `company_name, contact_phone, contact_email, source, status` +2. اذهب إلى **العملاء** → **استيراد** +3. ارفع الملف +4. تحقق من التطابق + +### استيراد الصفقات +1. جهز ملف CSV: `title, value, stage, assigned_to` +2. المراحل المتاحة: `new`, `negotiation`, `proposal`, `closed_won`, `closed_lost` + +--- + +## 5. إعداد الامتثال + +### PDPL +- الموافقة **إلزامية** قبل أي رسالة صادرة +- النظام يتحقق تلقائياً — لا تحتاج إعداد +- الموافقة تنتهي تلقائياً بعد 12 شهر + +### مراجعة الامتثال +1. اذهب إلى **الامتثال** → **المصفوفة** +2. اضغط "تشغيل الفحص" +3. راجع النتائج — أخضر (ممتثل) / أصفر (جزئي) / أحمر (غير ممتثل) + +--- + +## 6. إعداد Executive Room + +### للمدير التنفيذي +1. أنشئ حساب بدور `manager` أو `admin` +2. افتح **غرفة القيادة** من القائمة +3. سيرى: + - الإيرادات الفعلية مقابل التوقعات + - الموافقات المعلقة مع SLA + - حالة الامتثال + - حالة الموصلات + +### للمراجعة الأسبوعية +استخدم `GET /api/v1/executive-room/weekly-pack` للحصول على تقرير أسبوعي مهيكل. + +--- + +## 7. التحقق النهائي + +- [ ] كل أعضاء الفريق سجلوا دخولهم +- [ ] WhatsApp يرسل ويستقبل +- [ ] البريد الإلكتروني يعمل +- [ ] SLA مُعدّ +- [ ] 5+ صفقات مُدخلة +- [ ] Executive Room تعرض بيانات +- [ ] فحص الامتثال نجح + +**إذا كل شيء أخضر، النظام جاهز للاستخدام اليومي.** diff --git a/salesflow-saas/revenue-activation/deployment/EXECUTIVE_QUICKSTART.md b/salesflow-saas/revenue-activation/deployment/EXECUTIVE_QUICKSTART.md new file mode 100644 index 00000000..c7f45f28 --- /dev/null +++ b/salesflow-saas/revenue-activation/deployment/EXECUTIVE_QUICKSTART.md @@ -0,0 +1,77 @@ +# البداية السريعة للمدير التنفيذي — Executive Quickstart + +> **المدة**: 5 دقائق +> **الهدف**: تعرف بالضبط ما الذي يقدمه لك Dealix كل يوم + +--- + +## ادخل على غرفة القيادة + +افتح المتصفح → `https://[your-domain]/` → سجّل دخول → **غرفة القيادة** + +--- + +## ماذا سترى؟ + +### 1. الإيرادات +| المقياس | المعنى | +|---------|--------| +| **الإيراد الفعلي** | مجموع الصفقات المقفلة (ريال سعودي) | +| **التوقعات** | الإيراد المتوقع بناءً على الأنبوب | +| **الانحراف** | الفرق بين الفعلي والمتوقع | +| **معدل الفوز** | نسبة الصفقات الفائزة من إجمالي المغلقة | + +### 2. الموافقات +| اللون | المعنى | +|-------|--------| +| **أخضر** | ضمن المهلة — كل شيء تمام | +| **أصفر** | تحذير — اقتربت من SLA | +| **أحمر** | خرق SLA — تحتاج تدخلك الآن | + +**اضغط على أي موافقة → وافق أو ارفض بضغطة واحدة** + +### 3. الامتثال +- **ممتثل**: الضوابط التنظيمية مطبقة +- **جزئي**: بعض الضوابط تحتاج اكتمال +- **غير ممتثل**: يحتاج تدخل عاجل + +### 4. الموصلات +حالة التكاملات (واتساب، CRM، المدفوعات، البريد) + +### 5. التناقضات +إذا النظام اكتشف تضارب بين القرارات أو السياسات، يظهر هنا. + +--- + +## 3 أشياء تفعلها كل يوم + +1. **افتح غرفة القيادة** — ثق بالأرقام، هي من بياناتك الحقيقية +2. **وافق أو ارفض** — أي شيء أصفر أو أحمر يحتاج قرارك +3. **راجع المخاطر** — إذا فيه تناقض أو عدم امتثال، اضغط عليه + +--- + +## التقرير الأسبوعي + +كل أسبوع يُنتج النظام **Executive Weekly Pack** يحتوي: +- حالة عامة (أخضر/أصفر/أحمر) +- ما تحقق هذا الأسبوع +- ما هو معلّق +- المخاطر الحالية +- الفعلي مقابل الهدف + +--- + +## أسئلة شائعة + +**"كيف أعرف أن الأرقام صحيحة؟"** +كل رقم يأتي مباشرة من قاعدة بياناتك. لا يوجد تقدير يدوي. + +**"كيف أعرف أن القرار مثبت؟"** +كل قرار يُنتج حزمة أدلة (Evidence Pack) مع توقيع رقمي SHA256. + +**"ماذا لو رفضت موافقة؟"** +الإجراء يتوقف تلقائياً. لا يوجد bypass. + +**"هل بياناتي آمنة؟"** +PDPL مدمج — لا رسالة تُرسل بدون موافقة. كل تغيير مُسجّل في سجل التدقيق.