DMTX 联系人组合主键能力技术方案

1. 需求概述

• 配置用户：租户管理员或实施管理员。
• 使用用户：运营人员在导入联系人、同步会员资料、查询客户属性、做分群和旅程时受益，但不需要理解底层实现。
• 默认边界：未启用组合主键的租户保持当前单字段主键逻辑。
• v1 限制：每个租户同一时间只允许启用一套联系人身份识别规则。

2. 竞品方案调研

• HubSpot Knowledge Base：Deduplicate records in HubSpot
• HubSpot Developer Docs：CRM API Contacts
• Klaviyo Developers：Profiles API overview
• Klaviyo Developers：Custom integration FAQs
• Salesforce Developers：Register Contacts with Marketing Cloud Mobile SDK
• Salesforce Help：Subscriber Key in Marketing Cloud Engagement

3. 当前系统现状与影响面分析

4. 用户体验设计

5. 技术方案

推荐采用 “稳定内部 ID + 管理员可配置组合匹配键” 的双层身份方案：继续使用 contact.id 作为物理主键，继续使用 customer_id/contact_id 作为 DMTX 内部稳定身份和下游关联键；新增规则表、规则字段表、身份索引表和冲突表；组合键只决定“找到谁、更新谁、新建谁、是否冲突”，不直接替换下游 customer_id。

身份解析流程

• email 只作为组合键的一部分，不再单独决定“同一联系人”。
• cardNo + email 同时一致才命中同一联系人。
• cardNo 命中 A、email 命中 B 时视为冲突，不自动合并。
• 字段名必须来自元数据白名单，禁止开放拼接任意列名。

数据模型变更

CREATE UNIQUE INDEX ux_contact_identity_rule_enabled
ON contact_identity_rule(company_id, object_type)
WHERE status = 'ENABLED';

CREATE UNIQUE INDEX ux_contact_identity_value_active
ON contact_identity_value(company_id, rule_id, composite_key_hash)
WHERE status = 'ACTIVE';

接口设计

GET /api/contact/identity-rules/current?companyId=10001

{
  "code": 200,
  "message": "success",
  "data": {
    "enabled": true,
    "ruleId": 9001,
    "ruleName": "酒店会员身份规则",
    "matchMode": "ALL_FIELDS",
    "status": "ENABLED",
    "version": 3,
    "fields": [
      { "fieldName": "cardNo", "displayName": "会员卡号", "required": true, "normalizer": "TRIM", "ordinal": 1 },
      { "fieldName": "email", "displayName": "邮箱", "required": true, "normalizer": "LOWER_TRIM", "ordinal": 2 }
    ],
    "conflictStrategy": "BLOCK_AND_REVIEW",
    "legacyFallbackEnabled": false
  }
}

POST /api/contact/identity-rules/preview

{
  "companyId": 10001,
  "ruleName": "酒店会员身份规则",
  "matchMode": "ALL_FIELDS",
  "fields": [
    { "fieldName": "cardNo", "normalizer": "TRIM", "required": true, "ordinal": 1 },
    { "fieldName": "email", "normalizer": "LOWER_TRIM", "required": true, "ordinal": 2 }
  ],
  "conflictStrategy": "BLOCK_AND_REVIEW"
}

{
  "code": 200,
  "message": "preview success",
  "data": {
    "totalContacts": 1200000,
    "canBuildIdentity": 1130000,
    "missingRequiredKey": 62000,
    "duplicateCompositeKey": 180,
    "partialConflict": 27,
    "estimatedIndexRows": 1130000,
    "canEnable": false,
    "downloadConflictFileUrl": "/api/contact/identity-rules/preview/9001/conflicts.csv"
  }
}

public class OpenAttributeDTO implements Serializable {
    private Long userId;
    private Long companyId;

    // 旧单字段模式，继续兼容
    private String name;
    private String value;

    // 新组合键模式
    private Map<String, String> keyAttributes;
    private Long identityRuleId;
}

{
  "companyId": 10001,
  "userId": 88,
  "keyAttributes": {
    "cardNo": "A001",
    "email": "zhangsan@example.com"
  }
}

{
  "code": 409,
  "message": "identity conflict",
  "data": {
    "conflictType": "PARTIAL_MATCH_DIFFERENT_CONTACT",
    "conflictId": 778812,
    "hint": "cardNo and email match different existing contacts; manual review required"
  }
}

后端与前端实现建议

contact/src/main/java/com/qdum/dmtx/biz/contact/service/identity/
├── ContactIdentityRuleService.java
├── ContactIdentityResolverService.java
├── ContactIdentityNormalizer.java
├── ContactIdentityIndexService.java
├── ContactIdentityConflictService.java
├── dto/ContactIdentityRuleDTO.java
├── dto/ContactIdentityResolveRequest.java
├── dto/ContactIdentityResolveResult.java
└── enums/IdentityResolveStatus.java

导入改造后的目标流程：

读取启用规则
  → 对每行提取组合字段
  → 规范化并生成 composite_key_hash
  → 批量查 contact_identity_value
  → 按结果分桶：更新 / 新增 / 缺失字段 / 冲突
  → 批量写 contact 和 contact_identity_value
  → 生成导入结果报告

6. 边界情况与风险

7. 工作量评估

8. 方案对比

9. 实施阶段计划

10. 测试与验证计划

11. 待确认问题

1. cardNo 是标准字段、扩展字段，还是客户导入时动态生成字段？
2. 酒店业务中 cardNo 是否全集团唯一，还是只在酒店/品牌维度内唯一？如果只在酒店内唯一，组合键可能需要 hotelCode + cardNo + email。
3. 缺少 cardNo 但有 email 的数据，客户希望拒绝、进入错误表，还是按旧 email 逻辑导入？本方案建议 v1 拒绝。
4. 客户是否已有历史数据被 email 合并覆盖？如果有，是否需要历史拆分工具？本方案当前只覆盖后续识别，不自动还原历史覆盖。
5. Open API 调用方是否能同步升级到 keyAttributes？如果不能，需要多长兼容期？
6. 组合字段后续是否允许修改？如果允许，需要明确变更流程和历史 alias 策略。

12. 质量自检评分

13. 最终建议

• 不改 contact 表物理主键。
• 不用多个 ifPk=true 伪装组合主键。
• 不再在组合规则启用后按 email 单字段静默合并。
• 所有写入入口统一走 ContactIdentityResolverService。
• 冲突阻断并审计，避免再次发生属性覆盖。