system-prompts-and-models-o.../dealix/docs/TARGETING_ACQUISITION_OS.md
Dealix Builder e106a9a0d2 feat(targeting+service+excellence): Saudi Targeting OS + Service Tower + Service Excellence — 38 modules + 62 endpoints + 105 tests
Targeting & Acquisition OS (16 modules) — نظام الاستهداف الذكي
- account_finder: account-first targeting; 12 buying signals; deterministic 10-25 accounts per (sector, city)
- buyer_role_mapper: 14 buyer roles + sector-specific buying-committee maps + role-based Arabic angles
- contact_source_policy: 12 sources (crm_customer→opt_out) with risk_score, channels-allowed, retention guidance, lawful_basis
- contactability_matrix: 5 action modes (suggest_only/draft_only/approval_required/approved_execute/blocked); opt-out always blocked
- linkedin_strategy: Lead Forms + Ads + manual ONLY; linkedin_do_not_do() locks scrape/auto-DM/auto-connect/extensions
- email_strategy: drafts + unsubscribe footer + domain-pacing (fresh/warmed/trusted/damaged) + spam-trigger risk
- whatsapp_strategy: opt-in only; rejects cold + risky phrases; opt-in template requires explicit purpose+company+unsubscribe
- social_strategy: official APIs only; listening + drafts; no auto-publish
- outreach_scheduler: day-by-day plans + daily limits + opt-out enforcement
- reputation_guard: bounce/complaint/opt-out thresholds → healthy/watch/pause + recovery actions per channel
- daily_autopilot: Arabic brief + 7 today actions + EOD report
- acquisition_scorecard: pipeline + meetings + risks + productivity_score
- self_growth_mode: 5 ICP focuses for Dealix; daily brief + monthly targets
- free_diagnostic: Free Growth Diagnostic (3 ops + msg + risk + plan) → paid pilot recommendation
- contract_drafts: Pilot/DPA/Referral/Agency/SOW outlines (legal_review_required, PDPL-aware)
- service_offers: 7 targeting-tier offers + recommend by customer-type

Service Tower (8 modules) — برج الخدمات الذاتية (12 productized services)
- service_catalog: 12 services with target_customer/outcome/inputs/workflow/deliverables/pricing/risk/proof/upgrade
- service_wizard: deterministic recommend (agency→partner; list→list_intelligence; founder→self_growth; CEO→exec_brief; budget≥2999→growth_os; default→first_10)
- mission_templates: workflow steps with approval gates + linked growth missions
- pricing_engine: SAR quotes scaled by company_size×urgency×channels_count + setup_fee + monthly_offer
- deliverables: client report outline + proof pack template + operator checklist (no live actions)
- service_scorecard: 0..100 score from drafts/replies/meetings/pipeline/CSAT
- whatsapp_ceo_control: daily brief, approval cards (≤3 buttons), risk alerts, EOD reports
- upgrade_paths: deterministic next-service recommendation + Arabic upsell messages

Service Excellence OS (8 modules) — مصنع الخدمات الممتازة
- feature_matrix: 12 must-have features per service + advanced/premium/future tiers
- service_scoring: 10-dimension excellence score (clarity, speed_to_value, automation, compliance, proof, upsell, uniqueness, scalability, ops_daily, proof_data) → launch_ready/beta_only/needs_work
- quality_review: 4 gates (proof / approval / pricing / channels) + status verdict; review_service_before_launch and review/all
- competitor_gap: 7 competitor categories (CRM, WhatsApp tools, email assistants, LinkedIn tools, agencies, revenue intelligence, generic AI) + Dealix advantages + do-not-copy
- proof_metrics: required metrics + ROI estimate (pipeline_x + closed_won_x) + Arabic summary
- research_lab: monthly brief + feature hypotheses + top-3 experiments + monthly review
- service_improvement_backlog: feedback→backlog conversion + impact/effort prioritization + weekly improvements
- launch_package: landing outline + sales script + 12-min demo script + 5-day onboarding checklist

Routers (3 new) — 62 endpoints
- /api/v1/targeting/* — 20 endpoints (accounts, buying-committee, contacts, uploaded-list, outreach, daily-autopilot, self-growth, reputation, linkedin, drafts, free-diagnostic, services, contracts)
- /api/v1/services/* — 20 endpoints (catalog, recommend, intake, start, workflow, deliverables, proof-pack, quote, setup-fee, monthly-offer, scorecard, upgrade-path, ceo daily-brief/approval-card/risk-alert/EOD)
- /api/v1/service-excellence/* — 22 endpoints (feature-matrix, score, quality-review, review/all, proof-metrics, roi-estimate, gap-analysis, research-brief, hypotheses, experiments, monthly-review, backlog, weekly-improvements, launch-package, landing/sales/demo/onboarding)

Tests (3 new files, 105 tests)
- test_targeting_os: 47 tests (Arabic accounts, buying committees, opt-out blocked, cold WA blocked, LinkedIn no-scraping, email unsubscribe, WA risk, outreach plan, reputation guard, self-growth, contracts, scorecard)
- test_service_tower: 38 tests (12+ services, all have pricing/proof/deliverables/approval, wizard recommendations, workflow includes approval, quote scales, CEO cards ≤3 buttons, no live send)
- test_service_excellence: 33 tests (feature matrix, score returns status, ALL services pass quality gates, ROI x-multiples, 7 competitor categories, hypotheses+experiments, backlog conversion, launch package complete, demo=12min)

Docs (3 new + 1 updated)
- TARGETING_ACQUISITION_OS.md (Arabic)
- SERVICE_TOWER_STRATEGY.md (Arabic)
- SERVICE_EXCELLENCE_OS.md (Arabic)
- DEALIX_100_PERCENT_LAUNCH_PLAN.md — added §36 Targeting OS + §37 Service Tower + §38 Service Excellence + §39 Landing Pages

Landing pages (4 new, RTL Arabic)
- services.html — 3 doors + 12 productized services
- free-diagnostic.html — free growth diagnostic
- first-10-opportunities.html — kill feature
- agency-partner.html — agency partner program

Test results
- 105/105 new tests pass
- Full suite: 768 passed, 2 skipped
- 0 existing tests broken

Safety + integration with previous layers
- Targeting OS uses contactability_matrix → ALL contacts gated before any send
- Service Tower's workflow includes approval gate; ALL services live_send_allowed=False
- Service Excellence quality_review BLOCKS launch on missing proof/approval/pricing/unsafe channels
- linkedin_do_not_do() encodes 8 explicit prohibitions (scraping/auto-DM/auto-connect/extensions)
- whatsapp_do_not_do() blocks cold sends + group scraping
- Contracts always: legal_review_required=True, not_legal_advice=True, PDPL sections present
- Self-Growth Mode lets Dealix target its OWN ICP using the same approval-first pipeline

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 17:11:00 +03:00

185 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Targeting & Acquisition OS — نظام الاستهداف الذكي
> **القاعدة:** Dealix لا يجمع كل شيء من كل مكان. يستهدف بذكاء، عبر مصادر مصرّح بها، مع موافقات بشرية، ومراقبة سمعة، وتعلّم يومي.
---
## 1. لماذا Targeting OS؟
أي أداة تستطيع جمع أرقام بالـ scraping. القوة الحقيقية:
- **Account-first**: ابحث عن الشركات قبل الأشخاص.
- **Buying Committee**: من غالباً يقرر داخل كل شركة؟
- **Contactability Gate**: هل التواصل مسموح؟
- **Channel Strategy**: ما القناة الأفضل لكل مصدر؟
- **Reputation Guard**: إذا تدهورت السمعة → أوقف القناة تلقائياً.
- **Daily Autopilot**: brief يومي + actions + Proof.
- **Self-Growth Mode**: Dealix يستهدف عملاءه بنفس النظام.
---
## 2. الوحدات (16 module)
| الوحدة | الدور |
|--------|------|
| `account_finder` | يحدد 10-25 شركة مناسبة لكل (sector, city). |
| `buyer_role_mapper` | 14 دور + خرائط buying committee حسب القطاع. |
| `contact_source_policy` | 12 مصدر، كل واحد له risk_score + channels مسموحة + retention. |
| `contactability_matrix` | 5 action modes: suggest_only / draft_only / approval_required / approved_execute / blocked. |
| `linkedin_strategy` | Lead Forms + Ads + Manual فقط. **لا scraping/auto-DM/auto-connect**. |
| `email_strategy` | Drafts + unsubscribe + pacing حسب domain reputation. |
| `whatsapp_strategy` | Opt-in only؛ rejects cold + risky phrases. |
| `social_strategy` | Listening + drafts فقط؛ لا auto-publish. |
| `outreach_scheduler` | Day-by-day plan + daily limits + opt-out enforcement. |
| `reputation_guard` | Bounce/complaint/opt-out thresholds → healthy/watch/pause. |
| `daily_autopilot` | Daily brief + 7 today actions + EOD report. |
| `acquisition_scorecard` | Pipeline / meetings / risks / productivity score. |
| `self_growth_mode` | Dealix ICP focus + daily brief + weekly learning. |
| `free_diagnostic` | Free 5-section Arabic diagnostic → paid pilot offer. |
| `contract_drafts` | Pilot/DPA/Referral/Agency/SOW outlines (legal review required). |
| `service_offers` | 7 targeting-tier offers + pricing + recommend. |
---
## 3. القنوات والقواعد
### LinkedIn
**الممنوع** (encoded in `linkedin_do_not_do()`):
- `scrape_profiles, auto_connect, auto_dm, browser_automation, fake_engagement, download_contacts_from_linkedin, buy_scraped_leads, use_unauthorized_extensions`.
**المسموح**:
- LinkedIn Lead Gen Forms (أساسي).
- LinkedIn Ads.
- البحث اليدوي المعتمد (manual research task).
- Connection requests يدوية بمسودات Dealix.
### WhatsApp
- لا cold بدون opt-in واضح.
- opt-in template يحتاج: اسم النشاط + الغرض + خيار الانسحاب.
- double opt-in موصى به.
### Email
- سياق واضح + unsubscribe.
- Pacing حسب `domain_reputation`: fresh/warmed/trusted/damaged.
- إيقاف على bounce ≥ 5%.
### Social
- API رسمية فقط.
- Listening مسموح.
- Replies = drafts بموافقة.
---
## 4. مصادر الـ Contacts (12)
| Source | Risk | Status الافتراضي |
|--------|------|-----------------|
| `crm_customer` | 5 | safe |
| `inbound_lead` | 5 | safe |
| `website_form` | 10 | safe |
| `linkedin_lead_form` | 10 | safe |
| `event_lead` | 20 | needs_review |
| `referral` | 25 | needs_review |
| `partner_intro` | 25 | needs_review |
| `manual_research` | 50 | needs_review |
| `uploaded_list` | 60 | needs_review |
| `unknown_source` | 80 | needs_review |
| `cold_list` | 95 | blocked (waتساب)/needs_review (إيميل) |
| `opt_out` | 100 | blocked (كل القنوات) |
---
## 5. Daily Operating Loop
```
صباحاً:
- 10 شركات جديدة مناسبة
- 5 رسائل drafts للموافقة
- 3 leads متأخرة (>72h)
- 1 فرصة شريك
- 1 خطر سمعة
ظهراً:
- اعتماد + إرسال 5 emails
- مراجعة 12 رقم بدون مصدر
- ديمو شريك
مساءً:
- 32 حساب تم تحليله
- 6 مسودات معتمدة
- 2 ردود إيجابية
- 1 اجتماع مجدول
- 8 مخاطر منعت
```
---
## 6. Self-Growth Mode
5 ICP focuses لـ Dealix نفسه:
1. وكالات تسويق B2B في الرياض.
2. شركات تدريب B2B في الرياض.
3. شركات استشارات نمو.
4. SaaS سعودية صغيرة-متوسطة.
5. وسطاء عقار B2B في جدة.
كل صباح: 10 شركات + 5 رسائل + اعتماد المؤسس.
أهداف شهرية: 30 Free Diagnostic، 6 Paid Pilots، 3 Growth OS، 1 وكالة شريكة.
---
## 7. Endpoints (`/api/v1/targeting/...`)
```
POST /accounts/recommend
POST /buying-committee/map
POST /contacts/evaluate
POST /uploaded-list/analyze
POST /outreach/plan
GET /daily-autopilot/demo
GET /self-growth/demo
POST /self-growth/targets
POST /self-growth/weekly-report
GET /reputation/status
POST /reputation/recovery
POST /linkedin/strategy
POST /drafts/email
POST /drafts/whatsapp
POST /drafts/email-followup
POST /drafts/role-angle
POST /free-diagnostic
GET /services
POST /services/recommend
GET /contracts/templates
```
---
## 8. اختبارات
`tests/unit/test_targeting_os.py` — 47 اختبار:
- Account finder + Arabic + safe sources.
- Buying committee + role-based angles.
- Source classification + 12 sources.
- Contactability (opt-out, cold WA, inbound safe, unknown review).
- LinkedIn (لا scraping/auto-DM).
- Email risk + unsubscribe + 3-step follow-up.
- WhatsApp risk + opt-in templates.
- Outreach plan + daily limits.
- Reputation guard + recovery.
- Self-growth + free diagnostic + uploaded list preview.
- Contracts (legal review + PDPL).
- Acquisition scorecard.
---
## 9. ما لا تفعله
- لا scraping LinkedIn/social.
- لا auto-DM في أي منصة.
- لا cold WhatsApp.
- لا charge بدون تأكيد.
- لا scraping ToS-مخالف.
- لا وعود بنتائج مضمونة.
- لا تخزين بطاقات.