feat(dealix): full execution plan + endpoint inventory + customer docs

FULL_NEXT_STEP_AND_STACK_EXPANSION_AR.md: Complete execution plan with 8 gates, 5 phases, stack additions (OTel, OIDC, attestations, OpenFGA now; Great Expectations, Unstructured, Airbyte next; OPA, Temporal, MCP in radar), backend/frontend upgrades, and avoid-now list. docs/governance/endpoint-inventory.md: Trust classification for ALL ~70 endpoints: - ~45 Class A (safe auto, read-only) - ~15 Class B (approval-gated, side effects) - ~6 Class B+ (critical, financial/legal/irreversible) - 5 Class C (forbidden) With specific trust enforcement requirements per endpoint. Customer docs: ADMIN_SETUP_GUIDE.md — 30-60min setup guide for client IT admin (accounts, channels, approvals, data import, compliance, verification) EXECUTIVE_QUICKSTART.md — 5-min guide for CEO (what you see, 3 daily actions, weekly pack, FAQ) https://claude.ai/code/session_01W1rJthWDkasijTdXCfxVHs
2026-06-17 23:09:35 +00:00 · 2026-04-17 06:23:01 +00:00 · 2026-04-17 06:23:01 +00:00 · 43058e68cb
commit 43058e68cb
parent 91dc00f47f
4 changed files with 510 additions and 0 deletions
--- a/salesflow-saas/docs/FULL_NEXT_STEP_AND_STACK_EXPANSION_AR.md
+++ 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 | مختلف ≠ أفضل |
--- a/salesflow-saas/docs/governance/endpoint-inventory.md
+++ 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 |
--- a/salesflow-saas/revenue-activation/deployment/ADMIN_SETUP_GUIDE.md
+++ 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 تعرض بيانات
+- [ ] فحص الامتثال نجح
+
+**إذا كل شيء أخضر، النظام جاهز للاستخدام اليومي.**
--- a/salesflow-saas/revenue-activation/deployment/EXECUTIVE_QUICKSTART.md
+++ 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 مدمج — لا رسالة تُرسل بدون موافقة. كل تغيير مُسجّل في سجل التدقيق.