انتقل إلى المحتوى الرئيسي

سمات العملاء

سمات العملاء هي أزواج مرنة من المفتاح والقيمة يمكن إرفاقها بأي سجل عميل لتخزين بيانات التعريف المخصصة، وإعدادات التكوين، أو المعلومات الخاصة بالعمل التي لا تناسب حقول العملاء القياسية.

للتصنيف البصري للعملاء والروابط القابلة للنقر، راجع علامات العملاء. لمعلومات العملاء الأساسية، راجع العملاء، جهات الاتصال، المواقع والخدمات.

على عكس حقول قاعدة البيانات الثابتة، تتيح السمات لك توسيع سجلات العملاء ديناميكيًا دون تعديل مخطط قاعدة البيانات. وهذا يجعلها مثالية لتخزين بيانات محددة للنشر، ومعلمات التكامل، أو علامات منطق الأعمال المخصصة.

الغرض وحالات الاستخدام​

تشمل حالات ال��ستخدام الشائعة لسمات العملاء:

1. بيانات التكامل

تخزين معرفات النظام الخارجي أو مفاتيح API الخاصة بهذا العميل:

  • external_crm_id = "SF-12345" (معرف عميل Salesforce)
  • legacy_system_id = "OLD-CRM-789" (مرجع الهجرة)
  • hubspot_contact_id = "12345678" (تكامل HubSpot)

2. منطق الأعمال المخصص

تخزين علامات أو إعدادات تتحكم في سلوك محدد للعميل:

  • billing_method = "quarterly" (تجاوز الفوترة الشهرية الافتراضية)
  • auto_provision = "true" (تمكين توفير الخدمة تلقائيًا)
  • support_tier = "premium" (مستوى دعم مخصص)
  • credit_limit = "10000" (حد ائتماني خاص بالعميل)

3. بيانات الامتثال والتنظيم

تتبع البيانات الوصفية المتعلقة بالامتثال:

  • gdpr_consent_date = "2025-01-01" (موافقة معالجة البيانات)
  • tax_exempt = "true" (حالة الإعفاء الضريبي)
  • regulatory_entity = "FCC-123456" (معرف تنظيمي)

4. البيانات الوصفية التشغيلية

تخزين المعلو��ات التشغيلية:

  • preferred_contact_method = "email" (تفضيل الاتصال)
  • account_manager = "<john.smith@company.com>" (مدير الحساب المعين)
  • onboarding_date = "2025-01-15" (تتبع دورة حياة العميل)
  • churn_risk_score = "0.23" (تحليلات تنبؤية)

5. معلمات التوفير

تخزين إعدادات التكوين الخاصة بالتوفير:

  • radius_username_format = "email" (تنسيق RADIUS مخصص)
  • vlan_id = "100" (تكوين الشبكة)
  • ipv6_enabled = "true" (علامات الميزات)

السمات مقابل الحقول القياسية​

استخدم السمات عندما:

  • تكون البيانات محددة للنشر أو تختلف حسب التثبيت
  • تتغير المتطلبات بشكل متكرر
  • تخزين البيانات الوصفية الخاصة بالتكامل
  • تصميم ميزات جديدة قبل إضافة حقول قاعدة البيانات
  • لا تحتاج البيانات إلى استعلامات معقدة أو عمليات انضمام

استخدم الحقول القياسية عندما:

  • تكون البيانات أساسية لنموذج العميل (الاسم، البريد الإلكتروني، العنوان)
  • يتطلب الأمر بحثًا متكررًا أو تصفية أو تقارير
  • تحتوي البيانات على قيود سلامة مرجعية
  • تكون الأداء حاسمًا لاستعلامات كبيرة النطاق

إدارة السمات عبر واجهة المستخدم​

عرض سمات العملاء​

لعرض السمات لعميل:

  1. انتقل إلى صفحة نظرة عامة العميل
  2. انقر على علامة السمات
  3. سترى جدولًا بجميع السمات لهذا العميل، يظهر:
    • اسم السمة (المفتاح)
    • قيمة السمة
    • تاريخ الإنشاء
    • تاريخ آخر تعديل

إنشاء سمة جديدة​

لإنشاء سمة جديدة لعميل:

  1. انتقل إلى صفحة نظرة عامة العميل
  2. انقر على علامة السمات
  3. انقر على زر إضافة سمة
  4. املأ الحقول المطلوبة:
    • اسم السمة (مطلوب): المفتاح/الاسم لهذه السمة (مثل، external_crm_id)
    • قيمة السمة (مطلوب): القيمة التي سيتم تخزينها (مثل، SF-12345)
  5. انقر على إنشاء سمة

قواعد التسمية:

  • استخدم الأحرف الصغيرة مع الشرطات السفلية: external_system_id ✓
  • تجنب المسافات: external system id ✗
  • اجعل الأسماء وصفية ولكن مختصرة
  • استخدم تسمية متسقة عبر العملاء لنفس أنواع السمات

تعديل سمة​

لتعديل سمة موجودة:

  1. انتقل إلى صفحة نظرة عامة العميل
  2. انقر على علامة السمات
  3. ابحث عن السمة التي تريد تعديلها في الجدول
  4. انقر على زر تعديل (قلم)
  5. عدل اسم السمة أو قيمتها
  6. انقر على تحديث السمة

::: note ::: title ملاحظة :::

تغيير اسم السمة ينشئ زوج مفتاح-قيمة جديد. تأكد من أن هذا لا يكسر التكاملات التي تعتمد على اسم السمة الأصلي. :::

حذف سمة​

لحذف سمة:

  1. انتقل إلى صفحة نظرة عامة العميل
  2. انقر على علامة السمات
  3. ابحث عن السمة التي تريد حذفها في الجدول
  4. انقر على زر حذف (سلة المهملات)
  5. أكد الحذف في النافذة المنبثقة

::: warning ::: title تحذير :::

قد يؤدي حذف السمات المستخدمة من قبل التكاملات، أو سير العمل الخاص بالتوفير، أو منطق الفوترة إلى حدوث فشل. تحقق من الاعتماديات قبل الحذف. :::

مرجع حقل السمة​

تكامل API​

يمكن إدارة السمات برمجيًا عبر API:

إنشاء أو تحديث سمة​

نقطة النهاية: PUT /crm/attribute/

الإذن المطلوب: create_customer_attribute

جسم الطلب:

{
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345"
}

الاستجابة:

{
  "attribute_id": 456,
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345",
  "created": "2025-01-04 10:30:00",
  "last_modified": "2025-01-04 10:30:00"
}

تحديث سمة موجودة​

نقطة النهاية: PATCH /crm/attribute/attribute_id/{attribute_id}

الإذن المطلوب: update_customer_attribute

جسم الطلب:

{
  "attribute_value": "SF-54321"
}

الحصول على سمة بواسطة المعرف​

نقطة النهاية: GET /crm/attribute/attribute_id/{attribute_id}

الإذن المطلوب: view_customer_attribute

الاستجابة:

{
  "attribute_id": 456,
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345",
  "created": "2025-01-04 10:30:00",
  "last_modified": "2025-01-04 10:30:00"
}

الحصول على جميع السمات بواسطة معرف العميل​

نقطة النهاية: GET /crm/attribute/customer_id/{customer_id}

الإذن المطلوب: view_customer_attribute

الاستجابة:

[
  {
    "attribute_id": 456,
    "customer_id": 123,
    "attribute_name": "external_crm_id",
    "attribute_value": "SF-12345",
    "created": "2025-01-04 10:30:00",
    "last_modified": "2025-01-04 10:30:00"
  },
  {
    "attribute_id": 457,
    "customer_id": 123,
    "attribute_name": "billing_method",
    "attribute_value": "quarterly",
    "created": "2025-01-04 10:35:00",
    "last_modified": "2025-01-04 10:35:00"
  }
]

حذف سمة​

نقطة النهاية: DELETE /crm/attribute/attribute_id/{attribute_id}

الإذن المطلوب: delete_customer_attribute

الاستجابة:

{
  "result": "success"
}

عمليات السمات بالجملة​

إدارة سمات متعددة​

لتعيين سمات متعد��ة لعميل مرة واحدة (مثل، أثناء عملية الانضمام أو مزامنة التكامل):

import requests

customer_id = 123
attributes = [
    {"attribute_name": "external_crm_id", "attribute_value": "SF-12345"},
    {"attribute_name": "billing_method", "attribute_value": "quarterly"},
    {"attribute_name": "support_tier", "attribute_value": "premium"}
]

for attr in attributes:
    attr["customer_id"] = customer_id
    requests.put(
        "https://api.example.com/crm/attribute/",
        json=attr,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )

استعلام العملاء حسب السمة​

بينما لا تحتوي السمات على نقاط نهاية بحث مدمجة، يمكنك تصفية العملاء حسب السمة باستخدام API بحث العملاء مع تصفية مخصصة:

# الحصول على جميع العملاء، ثم تصفية حسب السمة في كود التطبيق
customers = requests.get("https://api.example.com/crm/customer/").json()

for customer in customers:
    attributes = requests.get(
        f"https://api.example.com/crm/attribute/customer_id/{customer['customer_id']}"
    ).json()

    # العثور على العملاء مع سمة محددة
    for attr in attributes:
        if attr['attribute_name'] == 'support_tier' and attr['attribute_value'] == 'premium':
            print(f"عميل مميز: {customer['customer_name']}")

::: note ::: title ملاحظة :::

للاستعلامات المتكررة المعتمدة على السمات، ضع في اعتبارك إضافة حقول قاعدة بيانات مفهرسة أو تنفيذ نقطة نهاية بحث مخصصة. :::

أفضل الممارسات​

1. قواعد التسمية

  • استخدم snake_case: external_system_id ✓
  • كن وصفيًا: billing_method ✓ مقابل method ✗
  • تجنب الكلمات المحجوزة أو الأحرف الخاصة
  • وثق معاني السمات في دليل النشر الخاص بك

2. أنواع البيانات

  • تخزن السمات القيم كسلاسل نصية (حد أقصى 150 حرفًا)
  • بالنسبة للقيم البوليانية، استخدم "true"/"false" (حروف صغيرة)
  • بالنسبة للتواريخ، استخدم تنسيق ISO 8601: "2025-01-04 10:30:00"
  • بالنسبة لبيانات JSON الكبيرة، ضع في اعتبارك استخدام حقول قاعدة بيانات مخصصة بدلاً من ذلك

3. التحقق

  • تحقق من قيم السمات في كود التطبيق قبل الحفظ
  • استخدم تنسيقات قيمة متسقة عبر العملاء
  • وثق القيم المتوقعة لكل اسم سمة

4. الوثائق

  • حافظ على سجل بأسماء السمات وأغراضها
  • وثق الأنظمة/التكاملات التي تعتمد على سمات معينة
  • أدرج أمثلة على القيم الصالحة

5. الهجرة والتنظيف

  • قم بمراجعة السمات غير المستخدمة بانتظام
  • أزل السمات القديمة بعد عمليات الهجرة للنظام
  • قم بإصدار أسماء السمات عند تغيير المخططات (مثل، api_key_v2)

أمثلة على سير العمل​

تكامل الانضمام​

عند ترحيل العملاء من نظام قديم:

# تخزين مرجع النظام القديم لأغراض التصحيح
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "legacy_crm_id",
  "attribute_value": "OLD-12345"
}

# تتبع تاريخ الهجرة
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "migrated_date",
  "attribute_value": "2025-01-04"
}

قواعد الفوترة المخصصة​

تجاوز دو��ة الفوترة الافتراضية لعميل محدد:

# تعيين فوترة ربع سنوية
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "billing_cycle",
  "attribute_value": "quarterly"
}

# ثم في كود الفوترة، تحقق من السمة قبل المعالجة
attributes = GET /crm/attribute/customer_id/123
billing_cycle = next(
    (a['attribute_value'] for a in attributes if a['attribute_name'] == 'billing_cycle'),
    'monthly'  # الافتراضي
)

علامات الميزات​

تمكين الميزات التجريبية لعملاء محددين:

# تمكين توفير IPv6
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "feature_ipv6_enabled",
  "attribute_value": "true"
}

الأذونات​

تتطلب عمليات السمات الأذونات التالية:

  • view_customer_attribute - عرض السمات
  • create_customer_attribute - إنشاء سمات جديدة
  • update_customer_attribute - تعديل السمات الموجودة
  • delete_customer_attribute - إزالة السمات

راجع rbac لتكوين التحكم في الوصول القائم على الدور.

استكشاف الأخطاء وإصلاحها​

السمة لا تظهر في واجهة المستخدم

  • تحقق من أنه تم إنشاء السمة (تحقق من استجابة API)
  • قم بتحديث الصفحة لإعادة تحميل بيانات العميل
  • تحقق من أن المستخدم لديه إذن view_customer_attribute

لا يمكن تحديث السمة

  • تأكد من أن لديك إذن update_customer_attribute
  • تحقق من أن attribute_id صحيح
  • تحقق من أن السمة تنتمي إلى العميل المحدد

فشل التكامل بعد حذف السمة

  • استعد السمة بالقيمة السابقة
  • قم بتحديث كود التكامل للتعامل مع السمات المفقودة بشكل سلس
  • قم بمراجعة اعتماديات السمة قبل الحذف

قيمة السمة مقطوعة

  • تحتوي قيم السمات على حد 150 حرفًا
  • بالنسبة للبيانات الأطول، قسمها إلى سمات متعددة أو استخدم حقل ملاحظات العميل
  • ضع في اعتبارك تخزين البيانات الكبيرة في حقول قاعدة بيانات مخصصة