跳到主要内容

客户属性

客户属性是灵活的键值对，可以附加到任何客户记录上，以存储自定义元数据、配置设置或不适合标准客户字段的业务特定信息。

有关可视化客户分类和可点击链接，请参见 客户标签。有关基本客户信息，请参见 客户、联系人、站点和服务。

与固定数据库字段不同，属性允许您动态扩展客户记录，而无需修改数据库架构。这使它们非常适合存储特定于部署的数据、集成参数或自定义业务逻辑标志。

目的和用例​

客户属性的常见用例包括：

1. 集成数据

存储特定于此客户的外部系统标识符或API密钥：

  • external_crm_id = "SF-12345"（Salesforce客户ID）
  • 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"（功能标志）

属性与标准字段​

使用属性的情况：

  • 数据是特定于部署的或因安装而异
  • 需求频繁变化
  • 存储特定于集成的元数据
  • 在添加数据库字段之前原型化新功能
  • 数据不需要复杂的查询或连接

使用标准字段的情况：

  • 数据是客户模型的核心（姓名、电子邮件、地址）
  • 需要频繁搜索、过滤或报告
  • 数据具有引用完整性约束
  • 对于大规模查询，性能至关重要

通过UI管理属性​

查看客户属性​

要查看客户的属性：

  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"
}

按ID获取属性​

端点： 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"
}

按客户ID获取所有属性​

端点： 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"Premium customer: {customer['customer_name']}")

::: note ::: title 注意 :::

对于频繁的基于属性的查询，考虑添加索引数据库字段或实现专用搜索端点。 :::

最佳实践​

1. 命名约定

  • 使用蛇形命名法：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 以获取基于角色的访问控制配置。

故障排除​

属性未在UI中出现

  • 验证属性是否已创建（检查API响应）
  • 刷新页面以重新加载客户数据
  • 检查用户是否具有 view_customer_attribute 权限

无法更新属性

  • 确保您具有 update_customer_attribute 权限
  • 验证 attribute_id 是否正确
  • 检查属性是否属于指定客户

属性删除后集成失败

  • 使用之前的值恢复属性
  • 更新集成代码以优雅地处理缺失的属性
  • 在删除之前审核属性依赖关系

属性值被截断

  • 属性值有150个字符的限制
  • 对于更长的数据，将其拆分为多个属性或使用客户备注字段
  • 考虑将大型数据存储在专用数据库字段中