ماژول CRM — تحلیل تفصیلی
Contacts · Deals · Pipelines · Automation

۱ جایگاه و محدوده ماژول

۱.۱ چرا CRM اولین ماژول است؟

۱.۲ محدوده ماژول (Scope) و آنچه خارج از آن است

۱.۳ نقشه همکاری ماژول‌ها

        ┌──────────────────────────────────────────────┐
        │            automation-core (هسته)            │
        │  موتور اجرا · رجیستری گره · بیلینگ · tenant   │
        └───────────────────┬──────────────────────────┘
                            │ (ثبت گره‌ها و متریک‌ها)
       ┌────────────────────┼────────────────────┬───────────────────┐
       ▼                    ▼                    ▼                   ▼
┌─────────────┐   ┌─────────────────┐  ┌─────────────────┐ ┌──────────────┐
│ module-crm  │◄──│ module-messaging│  │ module-payment  │ │ module-       │
│ (این سند)   │   │ پیامک/ایمیل/    │  │ درگاه/فاکتور    │ │ analytics     │
│             │   │ واتس‌اپ/تلگرام  │  │                 │ │ گزارش‌ها      │
└─────────────┘   └─────────────────┘  └─────────────────┘ └──────────────┘
       ▲
       │ گره‌های CRM که ماژول‌های دیگر مصرف می‌کنند:
       │ crm.contact.create · crm.deal.move_stage · crm.activity.log
       └──────────────────────────────────────────────────────────────

۲ دامنه کسب‌وکار (Domain Model)

۲.۱ موجودیت‌های اصلی

طراحی دامنه CRM بر پایه ۱۱ موجودیت اصلی انجام می‌شود. هر موجودیت یک مفهوم کسب‌وکاری مستقل است و در گره‌های اتوماسیون قابل ارجاع خواهد بود.

۲.۲ نمودار روابط موجودیت‌ها (ERD)

                    ┌───────────────┐
                    │   companies   │
                    │ name, domain  │
                    └───────┬───────┘
                            │ 1:N
                            ▼
┌───────────────┐   N:1  ┌───────────────┐   N:M   ┌──────────┐
│   segments    │◄──────►│   contacts    │◄───────►│   tags   │
│ (dynamic)     │        │ email, mobile │         │  color   │
└───────────────┘        │ score, status │         └──────────┘
                         └───┬───────┬───┘
                             │       │
                   1:N       │       │     1:N
                             ▼       ▼
              ┌────────────────┐  ┌──────────────────┐
              │    deals       │  │   activities     │
              │ amount, stage  │  │ type, body, ts   │
              │ close_date     │  └──────────────────┘
              └───────┬────────┘
                      │ N:1
                      ▼
              ┌────────────────┐   1:N   ┌──────────────────┐
              │   pipelines    │────────►│     stages       │
              │ name, is_default│        │ order, prob.     │
              └────────────────┘        └──────────────────┘

              ┌────────────────┐        ┌──────────────────┐
              │ custom_fields  │        │   lead_forms     │
              │ entity, type   │        │ public_token     │
              └────────────────┘        └──────────────────┘
              ┌────────────────┐        ┌──────────────────┐
              │  assignment_   │        │   crm_tasks      │
              │  rules         │        │ due_at, assignee │
              └────────────────┘        └──────────────────┘
              ┌────────────────┐
              │  field_values  │  (مقادیر فیلد سفارشی — JSON)
              └────────────────┘

۲.۳ چرخه حیات مخاطب (Contact Lifecycle)

  [ورود از فرم/وب‌هوک/API/ورود دستی]
                 │
                 ▼
          ┌─────────────┐
          │  new (لید)  │  ← امتیاز اولیه = 0
          └──────┬──────┘
                 │ (قوانین امتیازدهی)
       ┌─────────┴─────────┐
       ▼                   ▼
  ┌─────────┐        ┌──────────────┐
  │  cold   │        │  qualified   │  ← MQL (امتیاز ≥ آستانه)
  └────┬────┘        └──────┬───────┘
       │                    │ (تخصیص به کارشناس)
       │                    ▼
       │             ┌──────────────┐
       │             │    lead →    │
       │             │  contacted   │  ← اولین فعالیت ثبت شد
       │             └──────┬───────┘
       │                    ▼
       │             ┌──────────────┐
       │             │  nurturing   │  ← دنبال‌سازی زمان‌بندی‌شده
       │             └──────┬───────┘
       │                    │ (ایجاد Deal)
       └────────►┌──────────▼──────────┐
                 │      customer        │  ← Deal به مرحله «برنده» رسید
                 └──────────┬──────────┘
                            ▼
                     ┌─────────────┐
                     │ churned /   │  ← عدم خرید مجدد پس از N روز
                     │  inactive   │
                     └─────────────┘

۳ مدل داده و جداول

۳.۱ جدول‌های ماژول (پیشوند crm_)

۳.۲ نمونه Migration (جدول مخاطبان)

// app/Modules/Crm/Database/Migrations/..._create_crm_contacts_table.php
Schema::create('crm_contacts', function (Blueprint $t) {
    $t->id();
    $t->foreignId('tenant_id')->constrained()->cascadeOnDelete();
    $t->foreignId('company_id')->nullable()->constrained('crm_companies')->nullOnDelete();
    $t->foreignId('owner_user_id')->nullable()->constrained('users')->nullOnDelete();

    $t->string('first_name', 80)->nullable();
    $t->string('last_name', 80)->nullable();
    $t->string('email', 190)->nullable();
    $t->string('mobile', 32)->nullable();
    $t->string('status', 24)->default('new');   // new|qualified|contacted|nurturing|customer|churned
    $t->integer('score')->default(0);
    $t->string('source', 40)->nullable();      // form|webhook|api|manual|import
    $t->timestamp('last_activity_at')->nullable();
    $t->json('meta')->nullable();
    $t->timestamps();
    $t->softDeletes();                        // حذف منطقی برای احترام به داده مشتری

    $t->unique(['tenant_id', 'email']);
    $t->index(['tenant_id', 'mobile']);
    $t->index(['tenant_id', 'status', 'score']);
    $t->index(['tenant_id', 'owner_user_id']);
});

۳.۳ تصمیم مهم: فیلدهای سفارشی — JSON یا EAV؟

الگوی مقداردهی: بر اساس type فیلد، مقدار در ستون متناظر نوشته می‌شود: text → value_text، number/currency → value_number، date → value_date، multi-select/json → value_json.

۴ قوانین کسب‌وکار (Business Rules)

این قوانین درون ماژول پیاده می‌شوند (نه در Workflow) چون رفتار پیش‌فرض و قابل پیش‌بینی مورد انتظار یک CRM هستند. اتوماسیون روی این قوانین سوار می‌شود، جایگزین آن‌ها نمی‌شود.

۴.۱ جلوگیری از تکرار مخاطب (Deduplication)

  ورودی جدید (فرم / وب‌هوک / API / دستی)
              │
              ▼
   ┌─────────────────────────────────────┐
   │ ۱) نرمال‌سازی                      │
   │    email  → lowercase + trim        │
   │    mobile → حذف +98 / 0 / فاصله‌ها  │
   └──────────────┬──────────────────────┘
                  ▼
   ┌─────────────────────────────────────┐
   │ ۲) جست‌وجو در (tenant_id, email)    │
   │    یا (tenant_id, mobile)           │
   └──────────────┬──────────────────────┘
        ┌─────────┴─────────┐
        ▼                   ▼
   ┌─────────────┐   ┌──────────────────────────┐
   │ یافت نشد    │   │ یافت شد                  │
   │ → ایجاد جدید│   │ → سیاست قابل تنظیم tenant │
   └─────────────┘   │   (a) فقط به‌روزرسانی      │
                     │   (b) رد و لاگ conflict   │
                     │   (c) ادغام + ثبت در      │
                     │       crm_merge_logs      │
                     └──────────────────────────┘

کلید تشخیص ۱

email (نرمال‌شده)

کلید تشخیص ۲

mobile (نرمال‌شده به فرمت E.164 بدون +)

کلید تشخیص ۳

external_id (در صورت اتصال به سیستم بیرونی)

سیاست پیش‌فرض

update_only + ثبت رویداد crm.contact.updated

محدوده بررسی

فقط داخل همان tenant_id (هرگز بین مشتریان)

۴.۲ تخصیص خودکار (Assignment Strategies)

// مقدار اولویت‌بندی: اولین قاعده‌ی منطبق برنده است
{
  "strategy": "rule_based",
  "rules": [
    { "when": { "deal.amount": { "$gte": 100000000 } },
      "assign_to": "user:12", "priority": 1 },
    { "when": { "contact.source": "form", "contact.city": "tehran" },
      "assign_to": "pool:tehran_sales", "strategy": "round_robin" },
    { "when": {}, "assign_to": "pool:general", "priority": 999 }
  ]
}

۴.۳ امتیازدهی سرنخ (Lead Scoring)

فرمول کل

score = Σ (feature_points) − decay(age_days)

ورودی‌های مثبت

ایمیل شرکتی +15 · موبایل معتبر +10 · تکمیل فرم کامل +10 · دانلود محتوا +8 · بازدید صفحه قیمت +12

ورودی‌های منفی

ایمیل رایگان −5 · عدم فعالیت ۳۰ روز −15 · ایمیل نامعتبر −25

آستانه MQL

score ≥ 60 ⇒ status = qualified

بازمحاسبه

رویدادی (در هر فعالیت) + زمان‌بندی‌شده (شبانه برای decay)

۴.۴ رکود فرصت فروش (Deal Rotting)

• هر مرحله دارای rotting_days است (مثلاً «مذاکره» = ۷ روز).
• Job شبانه بررسی می‌کند: now() > stage_changed_at + rotting_days.
• در صورت رکود ⇒ تولید رویداد crm.deal.rotting و امکان اتوماسیون (هشدار به مدیر، تسک پیگیری).
• پرچم rotting_notified_at تا از ارسال تکراری هشدار جلوگیری کند.

۴.۵ حذف و حقوق داده (Privacy)

• حذف منطقی با softDeletes برای همه موجودیت‌های اصلی.
• حذف کامل (Hard Delete) فقط از طریق درخواست صریح tenant یا Super Admin.
• صادرات داده در قالب CSV/JSON برای هر tenant (حق انتقال داده).
• در نسخه Self-Hosted: هیچ داده‌ای به سرور ما ارسال نمی‌شود؛ فقط شمارنده مصرف (بدون محتوا).

۵ گره‌های اتوماسیون (Nodes)

ماژول CRM مجموعاً ۲۲ گره در هسته ثبت می‌کند: ۸ محرک (Trigger)، ۹ اقدام (Action) و ۵ شرط (Condition). این گره‌ها تنها چیزی‌ست که مشتری در Builder می‌بیند.

۵.۱ محرک‌ها (Triggers) — ۸ گره

۵.۲ اقدام‌ها (Actions) — ۹ گره

۵.۳ شرط‌ها (Conditions) — ۵ گره

۶ قرارداد Schema گره‌ها

هر گره باید بتواند خودش را توصیف کند. پنل Nuxt از همین توصیف، فرم پیکربندی، اعتبارسنجی، auto-complete متغیرها و پیش‌نمایش را می‌سازد. بنابراین افزودن گره جدید هیچ تغییری در فرانت لازم ندارد.

۶.۱ ساختار schema — نمونه کامل

{
  "slug": "crm.contact.create",
  "label": "ایجاد مخاطب",
  "category": "crm.contact",
  "kind": "action",                    // trigger | action | condition
  "icon": "user-plus",
  "color": "#5b9dff",
  "docs_url": "https://docs.example.com/modules/crm/contact-create",

  "fields": [
    { "key": "email", "label": "ایمیل", "type": "email",
      "required": false, "supports_variables": true },

    { "key": "mobile", "label": "موبایل", "type": "text",
      "required": false, "supports_variables": true,
      "hint": "فرمت‌های ۰۹۱۲... و +۹۸... خودکار نرمال‌سازی می‌شوند" },

    { "key": "owner_user_id", "label": "کارشناس مسئول",
      "type": "select", "options_source": "crm.users" },

    { "key": "tags", "label": "برچسب‌ها", "type": "multiselect",
      "options_source": "crm.tags", "allow_new": true },

    { "key": "on_conflict", "label": "در صورت تکراری بودن",
      "type": "select", "default": "update",
      "options": [
        { "value": "skip",   "label": "رد کن" },
        { "value": "update", "label": "به‌روزرسانی کن" },
        { "value": "merge",  "label": "ادغام کن" },
        { "value": "fail",   "label": "خطا بده" }
      ] },

    { "key": "custom", "label": "فیلدهای سفارشی",
      "type": "key_value",
      "dynamic_options_source": "crm.custom_fields:contact" }
  ],

  "validation": {
    "at_least_one": ["email", "mobile"],
    "message": "حداقل یکی از ایمیل یا موبایل باید وارد شود."
  },

  "output": {
    "contact": { "id": "string", "email": "string",
                  "mobile": "string", "status": "string" },
    "created": "boolean",
    "matched_by": "string"
  },

  "retry": { "max_attempts": 3, "backoff": "exponential" },
  "timeout_seconds": 10,
  "metering": "crm.contacts_written",
  "required_capability": "module.crm.write"
}

۶.۲ انواع فیلد پشتیبانی‌شده در پنل

۶.۳ پیاده‌سازی سمت سرور

// app/Modules/Crm/Actions/CreateContact.php
class CreateContact implements NodeContract
{
    public static function slug(): string { return 'crm.contact.create'; }

    public static function schema(): array
    {
        return [
            'kind'   => 'action',
            'label'  => 'ایجاد مخاطب',
            'fields' => [ /* ... مطابق بخش ۶.۱ ... */ ],
            'output' => ['contact' => 'object', 'created' => 'boolean'],
        ];
    }

    public function __construct(
        private readonly ContactService $contacts
    ) {}

    public function execute(NodeContext $ctx): NodeResult
    {
        $config = $ctx->config();      // متغیرها قبلاً resolve شده‌اند

        if (blank($config['email'] ?? null)
            && blank($config['mobile'] ?? null)) {
            throw new NodeValidationException(
                'حداقل یکی از ایمیل یا موبایل الزامی است.'
            );
        }

        [$contact, $created] = $this->contacts->upsert(
            tenant: $ctx->tenantId(),
            data:   $config,
            policy: $config['on_conflict'] ?? 'update',
            source: 'automation',
        );

        if ($created) {
            // تولید رویداد برای اتوماسیون‌های زنجیره‌ای بعدی
            ContactCreated::dispatch($contact, 'automation');
        }

        return NodeResult::make([
            'contact' => $contact->toNodeArray(),
            'created' => $created,
        ]);
    }

    public function retryPolicy(): RetryPolicy
    {
        return RetryPolicy::exponential(attempts: 3);
    }
}

۶.۴ ثبت گره‌ها در هسته (Service Provider)

// app/Modules/Crm/CrmServiceProvider.php
public function register(): void
{
    NodeRegistry::register(module: 'crm', version: '1.0.0', nodes: [
        // ── Triggers ──────────────────────────────────────────
        'crm.contact.created'        => Triggers\ContactCreated::class,
        'crm.contact.updated'        => Triggers\ContactUpdated::class,
        'crm.contact.status_changed' => Triggers\ContactStatusChanged::class,
        'crm.deal.created'           => Triggers\DealCreated::class,
        'crm.deal.stage_changed'     => Triggers\DealStageChanged::class,
        'crm.deal.rotting'           => Triggers\DealRotting::class,
        'crm.task.due'               => Triggers\TaskDue::class,
        'crm.lead_form.submitted'    => Triggers\LeadFormSubmitted::class,

        // ── Actions ───────────────────────────────────────────
        'crm.contact.create'         => Actions\CreateContact::class,
        'crm.contact.update'         => Actions\UpdateContact::class,
        'crm.contact.assign'         => Actions\AssignContact::class,
        'crm.contact.change_status'  => Actions\ChangeContactStatus::class,
        'crm.contact.add_tag'        => Actions\AddTag::class,
        'crm.contact.remove_tag'     => Actions\RemoveTag::class,
        'crm.deal.create'            => Actions\CreateDeal::class,
        'crm.deal.move_stage'        => Actions\MoveDealStage::class,
        'crm.activity.log'           => Actions\LogActivity::class,
        'crm.task.create'            => Actions\CreateTask::class,

        // ── Conditions ────────────────────────────────────────
        'crm.contact.exists'         => Conditions\ContactExists::class,
        'crm.contact.has_tag'        => Conditions\ContactHasTag::class,
        'crm.contact.score'          => Conditions\ContactScore::class,
        'crm.deal.in_stage'          => Conditions\DealInStage::class,
        'crm.segment.contains'       => Conditions\SegmentContains::class,
    ]);

    // متریک‌های مصرف این ماژول (برای بیلینگ پلن‌محور)
    UsageMeter::define('crm.contacts_written');
    UsageMeter::define('crm.deals_written');
    UsageMeter::define('crm.contacts_stored');   // gauge — نه شمارنده

    // منو و مجوزهای پنل
    AdminMenu::add('crm', 'CRM', capability: 'module.crm');
}

۷ API اختصاصی ماژول

ماژول CRM زیرمجموعه‌ای از قرارداد کلی /api/v1 است و همه قواعد سند ۰۱ (نسخه‌بندی، ساختار ثابت پاسخ، PlanGate، Idempotency) بر آن حاکم است.

۷.۱ نقاط پایانی

۷.۲ نمونه فراخوانی — ایجاد مخاطب از سیستم بیرونی

// POST /api/v1/crm/contacts
// Authorization: Bearer ak_live_xxxxxxxxxxxx
// Idempotency-Key: 4f1c9a7e-...   (اختیاری اما توصیه‌شده)

{
  "first_name": "مریم",
  "last_name":  "احمدی",
  "email":      "maryam@acme.ir",
  "mobile":     "09121234567",
  "source":     "api",
  "tags":       ["وبینار-مهر"],
  "custom":     { "city": "تهران", "budget": 50000000 }
}

// 201 Created
{
  "data": {
    "id":         "ctc_01J8X...",
    "status":     "new",
    "score":      25,
    "created":    true,
    "matched_by": null,
    "owner":      { "id": 12, "name": "کارشناس ۳" }
  },
  "meta": { "request_id": "req_...", "tenant": "acme" }
}

۷.۳ قواعد مهم API

۸ سناریوهای واقعی (Recipes)

این سناریوها در پنل به‌صورت قالب آماده (Template) ارائه می‌شوند تا مشتری با یک کلیک آن‌ها را نصب و شخصی‌سازی کند. هر قالب، ارزش فروش ملموس ایجاد می‌کند.

۹ رابط کاربری پنل CRM

ماژول CRM علاوه بر گره‌های اتوماسیون، یک پنل عملیاتی مستقل هم دارد؛ چون بدون محیط کار روزمره، مشتری CRM را قبول نمی‌کند. این پنل در Nuxt ساخته می‌شود و از همان REST API تغذیه می‌کند.

۹.۱ نقشه صفحه‌ها

۹.۲ اسکچ صفحه برد قیف (Kanban)

┌───────────────────────────────────────────────────────────────────────┐
│  CRM › قیف فروش  [قیف اصلی ▾]   [فیلتر: مالک ▾]  [+ فرصت]  [⚙ تنظیمات] │
├───────────────────────────────────────────────────────────────────────┤
│                                                                        │
│ ┌─ لید (۱۲) ─────┐ ┌─ مذاکره (۷) ────┐ ┌─ پیش‌فاکتور (۴) ─┐ ┌─ برده (۳) ┐│
│ ├────────────────┤ ├─────────────────┤ ├──────────────────┤ ├───────────┤│
│ │ ▢ شرکت آلفا    │ │ ▢ شرکت بتا      │ │ ▢ شرکت دلتا      │ │ ▢ شرکت ...││
│ │   ۵۰ م · ۳ روز │ │   ۱۲۰ م·۱۲ روز⚠│ │   ۸۰ م · ۲ روز   │ │   ۲۰۰ م   ││
│ ├────────────────┤ ├─────────────────┤ ├──────────────────┤ ├───────────┤│
│ │ ▢ شرکت گاما    │ │ ▢ شرکت زتا      │ │ ...              │ │ ...       ││
│ │   ۳۰ م · ۱ روز │ │   ۹۰ م · ۱ روز  │ │                  │ │           ││
│ └────────────────┘ └─────────────────┘ └──────────────────┘ └───────────┘│
│                                                                        │
│  ⚠ علامت هشدار = فرصت راکدتر از حد مجاز مرحله                          │
│  Drag & Drop یک کارت ⇒ API فراخوانی می‌شود ⇒ رویداد crm.deal.stage_    │
│  changed منتشر می‌شود ⇒ اتوماسیون‌های فعال در لحظه اجرا می‌شوند.        │
└───────────────────────────────────────────────────────────────────────┘

۹.۳ اجزای رابط کاربری مشترک

۱۰ مجوزها و نقش‌ها

۱۰.۱ سطوح دسترسی (Capabilities)

هر قابلیت یک اسلاگ دارد. نقش‌ها فقط مجموعه‌ای از این اسلاگ‌ها هستند و مشتری می‌تواند نقش سفارشی بسازد.

۱۰.۲ نقش‌های پیش‌فرض

۱۰.۳ اعمال مجوز در API

// app/Modules/Crm/Http/Controllers/ContactController.php
public function update(UpdateContactRequest $request, Contact $contact)
{
    $this->authorize('crm.contacts.update');

    // محدودیت مالکیت: کارشناس فقط مخاطب خودش را می‌بیند
    if (! $request->user()->can('crm.contacts.view_others')
        && $contact->owner_user_id !== $request->user()->id) {
        throw new AuthorizationException('دسترسی به این مخاطب مجاز نیست.');
    }

    $contact->update($request->validated());
    ContactUpdated::dispatch($contact, 'manual');

    return ContactResource::make($contact);
}

۱۱ متریک مصرف و سهم‌بندی با پلن

۱۱.۱ متریک‌های ماژول CRM

۱۱.۲ اختصاص سقف به پلن‌ها

* «نامحدود» در عمل با سیاست منع استفاده غیرمتعارف (Fair Usage) و پایش خودکار محدود می‌شود.

۱۱.۳ رفتار سیستم در رسیدن به سقف

  مصرف ماهانه = ۸۰٪ سقف
        │
        └─► بنر هشدار در پنل + ایمیل به Owner (یک‌بار در دوره)

  مصرف ماهانه = ۱۰۰٪ سقف
        │
        ├─► اجراهای جدید اتوماسیون مرتبط با CRM متوقف می‌شوند  ← 402
        ├─► خواندن داده همچنان آزاد است (مشتری داده‌اش را از دست نمی‌دهد)
        ├─► ورود داده دستی همچنان ممکن است (تجربه کار روزمره قطع نشود)
        └─► اعلان ارتقا + لینک مستقیم به صفحه صورتحساب

  گزینه Overage (اختیاری، فقط پلن Business و Enterprise)
        │
        └─► اجرای بیشتر مجاز است و هزینه مازاد در فاکتور دوره بعد محاسبه می‌شود

۱۱.۴ نکات پیاده‌سازی Metering

• شمارش در Redis برای سرعت، و همگام‌سازی دوره‌ای با جدول برای ماندگاری. کلید Redis: usage:{tenant_id}:{metric}:{YYYY-MM}.
• شمارش Gauge با هر ایجاد/حذف رکورد به‌روزرسانی می‌شود (نه با شمارش دوباره جدول).
• مسیر سرد (Cold path): بازمحاسبه شبانه از دیتابیس برای اصلاح خطای شمارش.
• مسیر گرم (Hot path): بررسی سقف باید در حافظه انجام شود؛ هرگز کوئری شمارشی سنگین روی مسیر درخواست کاربر نگذارید.
• بازنشانی ماهانه با Job زمان‌بندی‌شده در اولین روز ماه + تولید رکورد مصرف دوره گذشته برای صورتحساب.

۱۲ یکپارچه‌سازی با سرویس‌های بیرونی

ماژول CRM خودش پیام ارسال نمی‌کند؛ اما برای اینکه سناریوهای بخش ۸ کار کنند، باید بفهمیم CRM با چه سرویس‌هایی و از چه راهی گفتگو می‌کند.

۱۲.۱ جداسازی مسئولیت (Separation of Concerns)

┌────────────────────┐        ┌────────────────────────┐
│   module-crm       │        │  module-messaging      │
│  رویداد تولید می‌کند│───────►│  پیام ارسال می‌کند      │
│  crm.contact.created│  گره  │  sms.send · email.send  │
└────────────────────┘        └───────────┬────────────┘
                                          │
                              ┌───────────┼───────────┬──────────────┐
                              ▼           ▼           ▼              ▼
                        ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────────┐
                        │ کاوه‌نگار│ │ SMTP    │ │ واتس‌اپ  │ │ تلگرام     │
                        │ پیامک   │ │ اختصاصی │ │ Business │ │ Bot API    │
                        └─────────┘ └─────────┘ └──────────┘ └────────────┘
                        (کانکتورها در ماژول messaging پیاده می‌شوند)

۱۲.۲ کانکتورهای درون CRM (محدود)

۱۲.۳ امضای امنیتی وب‌هوک (HMAC)

هر وب‌هوک خروجی با امضای HMAC-SHA256 ارسال می‌شود تا مشتری بتواند اصالت آن را بررسی کند:

// هدرهای ارسالی
X-Automation-Event:    crm.contact.created
X-Automation-Delivery: dlv_01J8X...
X-Automation-Timestamp: 1758880000
X-Automation-Signature: sha256=<hmac>

// محاسبه امضا (سمت مشتری)
$signature = hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $tenantWebhookSecret
);

// بررسی: امضا برابر است و اختلاف زمانی کمتر از ۵ دقیقه (ضد Replay Attack)

۱۲.۴ سیاست تلاش مجدد در وب‌هوک خروجی

نکته: خطاهای 4xx (به‌جز 429) تکرار نمی‌شوند، چون نشانه اشکال در تنظیمات است نه مشکل موقت. این تفکیک از هدر رفتن منابع و سردرگمی مشتری جلوگیری می‌کند.

۱۳ تست و معیار پذیرش

۱۳.۱ ماتریس تست ماژول

۱۳.۲ تست نشت داده (Data Leakage Suite) — اجباری

// tests/Feature/Tenancy/CrmIsolationTest.php
class CrmIsolationTest extends TestCase
{
    public function test_tenant_cannot_read_other_tenant_contacts(): void
    {
        [$a, $b] = Tenant::factory()->count(2)->create();

        $contactB = Contact::factory()->for($b)->create();

        $this->actingAsTenant($a)
             ->getJson("/api/v1/crm/contacts/{$contactB->id}")
             ->assertNotFound();          // 404 — نه 403 (عدم افشای وجود)
    }

    public function test_export_never_includes_foreign_rows(): void
    {
        /* بررسی می‌شود که فایل CSV هیچ tenant_id دیگری نداشته باشد */
    }

    // این تست برای «همه» مدل‌های CRM به‌صورت DataProvider اجرا می‌شود
}

۱۳.۳ معیار پذیرش ماژول (Definition of Done)

۱۴ نقشه پیاده‌سازی ماژول

ماژول CRM در ۶ اسپرینت دو‌هفته‌ای (~۳ ماه) با یک توسعه‌دهنده تمام‌وقت به‌همراه هسته قابل تحویل است. ترتیب اسپرینت‌ها بر پایه «اول محصول قابل فروش» است، نه «اول معماری کامل».

۱۵ ریسک‌ها و سؤالات باز

۱۵.۱ ریسک‌های ماژول و راهکار کاهش

۱۵.۲ سؤالات باز برای تصمیم‌گیری

۱۵.۳ ماژول در یک نگاه