DMTX 联系人组合主键能力深入开发方案

1. 结论先行

1.1 当前系统真实现状

经过重新阅读 upload、ETL、DataClean、多主键配置和最终联系人写入链路，结论如下：

1.2 客户需求与当前能力的差距

酒店集团诉求不是“可以勾选多个主键字段”，因为 DMTX 已经能做到这一点。客户真正要的是：

当前系统的实际行为更接近：

if (email 命中联系人 A) OR (cardNo 命中联系人 B) then 返回 A/B 候选
if 候选数 > 1 then 自动合并为一个联系人

客户期望行为是：

if (email AND cardNo) 同时命中同一联系人 then 更新
else if 完整组合没有命中 then 新增
else if 组合字段分别命中不同联系人 then 标记冲突，不静默合并

1.3 推荐方案

推荐采用“兼容模式 + 组合规则模式”的身份规则层：

核心原则：

1. 不改 contact.id 物理主键，不把 MySQL/PG 联合主键直接搬到 contact 表。
2. 保留 customer_id / contact_id / user_ids_str 的现有内部身份模型。
3. if_pk 继续作为“可参与身份识别的字段”标记，不破坏现有多主键配置。
4. 新增一层规则计划，决定这些主键字段按 OR 使用，还是按组合组 AND 使用。
5. 先覆盖 ETL/SFTP/API/DataClean 主链路；旧联系人分组导入必须单独说明或迁移，否则会出现同一张 contact 表由两套身份引擎维护。

2. 需求与业务场景

2.1 客户原始需求

以当前沟通描述作为客户需求记录：

2.2 目标示例

2.3 验收标准

3. 竞品和行业经验

行业共识：

1. Email 不应被视为绝对唯一的人。
2. 企业级营销系统应保留内部 surrogate ID，同时支持业务身份规则。
3. 身份规则变化必须有预检、审计、冲突处理和回退路径。
4. 错误合并的成本通常高于保守地产生冲突记录。

4. 当前调用链重新梳理

4.1 旧联系人分组导入链路，未走 DataClean

这条链路是传统联系人分组导入，直接写 contact 表：

关键点：

• ContacatImportDisposeService.ContactImportSaveOrUpdate 按 onlyEmail、onlyMobile、emailMobile 分桶。
• 匹配逻辑硬编码 Email/Mobile，不读取 metadata_field.if_pk。
• Email 和 Mobile 分别命中不同联系人时，会合并字段/分组并删除其中一条联系人。
• 新增时 contact_id 和 customer_id 都设为新 UUID。

结论：如果产品说“用户 upload 上传开始就支持组合主键”，必须先确认当前前端使用的是这条 legacy 链路还是 ETL SFTP 链路。若仍使用 legacy 链路，酒店 MVP 不能只改 DataClean。

4.2 ETL/SFTP/API 导入链路，走 DataClean

这条链路是本方案优先改造的主链路：

API/SCRM 入口也会进入类似 DataClean 链路：

ELTApiService.userAnalysis / addOrDeleeCustomerToEtl
  -> EtlServiceApi.innerApiImport
  -> EtlApiResource.innerApiImport
  -> EtlApiService.innerApiImport
  -> ImportService.singleImport
  -> Redis etlImportServiceSingle:{cid}
  -> ImportRedisService.singleImportServiceByCid
  -> KafkaFirstConsumer.consume
  -> DataClean.batchCleanDo
  -> CustomerService.singleSaveOrUpdate

4.3 DataClean 当前多主键语义

关键代码事实：

当前语义可以概括为：

配置多个主键字段 = 多个可替代的身份信号
导入行至少提供一个信号即可
任一信号命中即可匹配
多个信号命中不同联系人时自动合并

这不是客户要的组合主键。

4.4 表单和事件路径也受影响

组合主键不能只改 type=user：

• type=event 在 DataClean.batchCleanDo 中当没有 uid 时也调用 searchUserByPks。
• type=form_user 会调用 searchUserByPks 或 searchFormUser；searchFormUser 会把 customer_id 追加到 PK 列表再调用 source.search(...)。
• 如果只改普通用户导入，表单提交和事件导入仍可能按 OR 逻辑错误合并或错误创建。

4.5 后台定时合并也是风险点

EsUser.mergeUsers(Long cid) 会遍历 attributesUtils.userPks(cid) 的每个主键字段，然后逐个调用 source.merge(cid, pk)。这意味着即使 DataClean 改成组合规则，只要这个定时任务仍按单字段主键合并，就会继续把“同邮箱不同会员卡”的联系人合并掉。

组合模式下必须：

1. 禁用该公司单字段定时合并，或
2. 改为按完整组合组执行合并，且冲突进入治理流程。

5. 目标架构

5.1 身份规则模型

推荐新增显式规则模型，而不是把多个 if_pk=true 直接解释成组合主键。

兼容层

没有配置新规则的公司，运行时合成一个兼容计划：

mode = ANY_KEY_COMPATIBLE
activeFields = all fields where ifShow && ifPk
runtimeGroups = 每个 PK 字段一个单字段组

组合层

启用组合规则的公司，运行时读取显式分组：

mode = GROUPED_COMPOSITE
groups:
  - groupCode: hotel_member
    fields: [cardNo, email]
    match: ALL_FIELDS
    conflictPolicy: REJECT_OR_PENDING

5.2 数据模型建议

平台化方案建议新增规则表；如果只做 MVP，也可以先在 metadata_field 增加分组字段，但不建议长期把规则塞进字段表。

推荐表结构

CREATE TABLE contact_identity_rule (
  id BIGSERIAL PRIMARY KEY,
  company_id BIGINT NOT NULL,
  object_type VARCHAR(32) NOT NULL DEFAULT 'contact',
  mode VARCHAR(32) NOT NULL DEFAULT 'ANY_KEY_COMPATIBLE',
  conflict_policy VARCHAR(32) NOT NULL DEFAULT 'REJECT',
  enabled BOOLEAN NOT NULL DEFAULT TRUE,
  version INT NOT NULL DEFAULT 1,
  status INT NOT NULL DEFAULT 0,
  create_by BIGINT,
  create_date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  update_by BIGINT,
  update_date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE contact_identity_rule_group (
  id BIGSERIAL PRIMARY KEY,
  rule_id BIGINT NOT NULL,
  group_code VARCHAR(64) NOT NULL,
  group_name VARCHAR(128),
  match_type VARCHAR(32) NOT NULL DEFAULT 'ALL_FIELDS',
  priority INT NOT NULL DEFAULT 0,
  status INT NOT NULL DEFAULT 0
);

CREATE TABLE contact_identity_rule_field (
  id BIGSERIAL PRIMARY KEY,
  group_id BIGINT NOT NULL,
  metadata_field_id BIGINT NOT NULL,
  field_name VARCHAR(128) NOT NULL,
  required BOOLEAN NOT NULL DEFAULT TRUE,
  order_no INT NOT NULL DEFAULT 0,
  normalize_type VARCHAR(32)
);

可选 MVP 字段

如果为了压缩开发范围，可以先在 metadata_field 增加：

但这种方案后续支持多组、版本、审计、回滚会吃力，建议只作为临时 MVP。

5.3 Java 运行时 DTO

建议新增不可变 DTO/record，便于测试和避免 DataClean 继续拿扁平 list 判断。

public enum ContactIdentityRuleMode {
    ANY_KEY_COMPATIBLE,
    GROUPED_COMPOSITE
}

public record ContactIdentityRulePlan(
    Long companyId,
    ContactIdentityRuleMode mode,
    List<ContactIdentityGroupPlan> groups
) {}

public record ContactIdentityGroupPlan(
    String groupCode,
    List<String> fieldNames,
    boolean complete,
    Map<String, String> normalizedValues
) {}

public record ContactIdentityMatchResult(
    boolean success,
    boolean conflict,
    String errorCode,
    String errorMessage,
    Map<String, List<LinkedHashMap<String, Object>>> matchesByGroup,
    List<LinkedHashMap<String, Object>> candidates
) {}

核心要求：GROUPED_COMPOSITE 不能再把查询结果压扁成 List<LinkedHashMap<...>> 后直接交给 handleUsers，否则不同组合组命中不同联系人时仍会被误判为“多个候选可合并”。

6. 从用户上传到最终写入的改造顺序

Step 1：配置层先显式建模，默认兼容

注意事项：

• 老 payload 不传新字段时必须默认 ANY_KEY_COMPATIBLE。
• Email/Mobile 取消主键的原有限制不能被绕过。
• 需要检查 MetadataService.updateFieldSuccessfulAfter 中问卷 PKConvertUpdate 返回码判断，避免规则更新出现“元数据已变更但外部同步失败”的半成功状态。

Step 2：在 AttributesUtils 统一生成规则计划

新增类似方法：

public ContactIdentityRulePlan contactIdentityRulePlan(Long cid);
public ContactIdentityRowPlan buildRowPlan(Long cid, Map<String, Object> properties);

行为：

Step 3：上传前校验和文件内去重先改

现状：pkMd5Summary 基于导入行中有值的 PK map 计算，重复行 isRepeat=true 但仍发送 Kafka。

组合模式建议：

1. GROUPED_COMPOSITE 下 hash 应基于完整组合组的规范化值。
2. 组内字段不完整，应在上传阶段报错，不要等 DataClean 里变成模糊新增。
3. 文件内完全重复行建议直接 skip 或记录为明确“重复跳过”，不要一边计数去重，一边仍下发 Kafka 更新数据。

Step 4：PostgreSQLSource 从 OR 查询升级为规则查询

当前查询：

select * from contact
where email = ? or mobile = ? or card_no = ?
order by create_date asc
limit 1000

组合模式应生成：

select contact_id, customer_id, create_date
from contact
where (email = ? and card_no = ?)
order by create_date asc
limit 1000

多个完整组时：

where (email = ? and card_no = ?)
   or (unionid = ? and appid = ?)

必须处理：

• 字段名只能来自元数据白名单并转换为合法列名，禁止用户输入字段直接拼接 SQL。
• 任一组合组必填字段规范化失败时 fail closed，不能降级成单字段查询。
• 查询异常不能返回空列表让 DataClean 当作新增，否则会产生重复联系人。
• 先查询窄字段，再按 contact_id 批量 hydrate 完整行，减少 select * 成本。

Step 5：DataClean 改为消费结构化匹配结果

涉及方法：

组合冲突建议策略：

Step 6：SourceCommon.merge 只处理真正重复，不处理组合冲突

当前 SourceCommon.merge 会：

• 第一个候选保留 uid/pid。
• 后续候选加入 uids/pids 删除列表。
• 非空字段合并，后面的非空值可覆盖前面的非空值。
• label_ids、user_ids_str 合并。

组合模式下，SourceCommon.merge 不应该承担“判断是否应该合并”的职责。判断必须在 DataClean/Resolver 层完成；只有确认这些候选是同一业务身份的重复联系人，才调用 merge。

Step 7：CustomerService 保持行模型，但修复写入结果契约

涉及方法：

• CustomerService.singleSaveOrUpdate
• CustomerService.saveCustomerToEs
• CustomerService.saveContact
• CustomerService.updateContact
• DataClean.storage

建议：

1. saveContact/updateContact 失败时返回明确失败项，不要只返回 0 后让上层继续记成功。
2. singleSaveOrUpdate 返回 per item 写入结果。
3. DataClean.storage 只有真实写成功才更新 SFTP 成功计数和 importRecordAsyncService.recordSuccess。
4. 组合冲突不进入写入队列。

这一步不是组合主键的核心功能，但关系到导入可信度。当前链路存在“DB 写失败但导入记录可能记成功”的静默失败风险，应纳入实施。

Step 8：定时合并任务组合化或禁用

涉及：

• EsUser.mergeUsers(Long cid)
• PostgreSQLSource.merge(cid, pk)

组合模式下不能继续按每个单字段主键做合并。建议：

Step 9：Legacy 上传链路明确阶段策略

旧链路不走 DataClean：

ContactInfoResource.uploadContact
  -> ContactGroupUploadService.contactImport/contactSave/uploadCsv
  -> ContacatImportDisposeService.ContactImportSaveOrUpdate
  -> direct SQL contact writes

如果酒店客户的“用户 upload 上传”实际使用这条路径，则有三种选择：

本方案建议：酒店 MVP 如果必须覆盖 UI 上传，优先做 A；否则只能称为“ETL 导入支持组合主键”，不能称为“全量上传支持”。

Step 10：下游以 customer_id 连续性做回归

组合主键不应把组合字段传递到所有下游表作为新关联键。下游仍用 customer_id/contact_id/user_ids_str：

7. 数据库、索引和并发设计

7.1 预审计

启用组合模式前必须做数据审计：

-- contact_id 重复检查
select contact_id, count(*)
from contact
where if_deleted = 0
group by contact_id
having count(*) > 1;

-- customer_id 重复检查
select customer_id, count(*)
from contact
where if_deleted = 0
group by customer_id
having count(*) > 1;

-- 酒店组合键潜在重复检查示例
select email, card_no, count(*)
from contact
where if_deleted = 0
  and email is not null
  and card_no is not null
group by email, card_no
having count(*) > 1;

7.2 索引策略

当前单字段索引不足以支撑 (email = ? AND card_no = ?)。组合组启用前应创建组合索引：

create index concurrently if not exists idx_contact_cid_email_cardno
on contact (email, card_no, create_date)
where if_deleted = 0;

建议：

• 按组合组创建索引，不为所有排列组合建索引。
• 字段顺序与规则组字段顺序一致。
• create_date 可作为尾列支持现有 oldest wins 的查询排序。
• 规则变更时需要索引生命周期：创建、验证、启用、废弃旧索引。

7.3 并发控制

当前 search → merge → update/delete 不是一个强事务闭环。并发导入同一组合键时可能重复新增或重叠合并。

建议在组合模式下增加锁：

lock key = companyId + ruleGroupCode + normalizedCompositeValuesHash

实现选择：

MVP 推荐使用 advisory lock 或 Redis lock，至少保证同一公司同一组合键不会并发新增两条。

7.4 冲突持久化

组合冲突不能只写日志，应落库或进入可查询队列：

CREATE TABLE contact_identity_conflict (
  id BIGSERIAL PRIMARY KEY,
  company_id BIGINT NOT NULL,
  rule_mode VARCHAR(32) NOT NULL,
  group_code VARCHAR(64),
  normalized_key VARCHAR(512) NOT NULL,
  source_type VARCHAR(32),
  source_id BIGINT,
  file_id BIGINT,
  row_no INT,
  payload JSONB,
  matched_contact_ids JSONB,
  status VARCHAR(32) NOT NULL DEFAULT 'PENDING',
  reason VARCHAR(256),
  create_date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  update_date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

用途：

• 导入结果页展示冲突数量。
• 管理员可下载冲突明细。
• 后续可做人工合并、忽略、重跑。

8. API 和用户体验

8.1 管理员配置体验

建议配置步骤不超过 3 步：

1. 进入“联系人字段 / 身份识别规则”。
2. 选择模式：兼容多主键 or 组合主键。
3. 选择组合字段并运行预检，预检通过后启用。

默认值：

8.2 配置 API 草案

GET /api/contact/v1/identity-rule

返回：

{
  "companyId": 1001,
  "mode": "GROUPED_COMPOSITE",
  "conflictPolicy": "REJECT",
  "groups": [
    {
      "groupCode": "hotel_member",
      "groupName": "酒店会员身份",
      "matchType": "ALL_FIELDS",
      "fields": ["card_no", "email"]
    }
  ]
}

PUT /api/contact/v1/identity-rule

请求：

{
  "mode": "GROUPED_COMPOSITE",
  "conflictPolicy": "REJECT",
  "groups": [
    {
      "groupCode": "hotel_member",
      "fieldNames": ["card_no", "email"]
    }
  ],
  "dryRun": true
}

dryRun=true 时返回预检结果，不落地启用。

8.3 导入预检展示

导入前建议展示：

9. 测试方案

9.1 单元测试

9.2 集成测试

使用 JUnit 5 + Testcontainers PostgreSQL：

1. 初始化 contact 表和代表性联系人。
2. 配置 ANY_KEY_COMPATIBLE，验证 Email/Mobile OR 命中和合并保持现状。
3. 配置 GROUPED_COMPOSITE(card_no + email)，验证：

• 同组合更新。
• 同 email 不同 cardNo 新增。
• cardNo/email 分别命中不同联系人时冲突。
• 查询异常不新增。

1. 验证组合索引存在时 EXPLAIN ANALYZE 使用合理计划。

9.3 E2E / 回归测试

10. 工作量评估

10.1 推荐拆分

10.2 总体估算

推荐路径：先做 ETL/DataClean MVP + legacy 上传路径产品确认。如果酒店客户实际使用旧联系人分组导入，则把 legacy 迁移纳入 MVP，否则上线口径会不完整。

11. 风险和防护

12. 发布与回滚策略

12.1 灰度顺序

1. 灰度公司只开启配置 UI，不改变运行时模式。
2. 运行数据审计：重复 contact_id/customer_id、潜在组合冲突、单字段合并历史。
3. 创建组合索引并验证 EXPLAIN。
4. 开启 shadow mode：同时计算 OR 结果和组合结果，只记录差异，不改变写入。
5. 开启 GROUPED_COMPOSITE，只覆盖 ETL/SFTP/API 导入。
6. 观察新增率、更新率、冲突率、导入失败率、写入失败率。
7. 决定是否迁移 legacy 上传路径。

12.2 回滚

13. 最终建议

本需求不应再表述为“DMTX 要支持多个主键”，因为当前已经支持多个 if_pk 主键字段，并且 Email/Mobile 可取消、自定义字段可设为主键。

准确表述应为：

推荐实施原则：

1. 保留存量 ANY_KEY_COMPATIBLE 默认模式。
2. 新增 GROUPED_COMPOSITE，只对显式开启公司生效。
3. 先统一 ETL/DataClean 主链路，再处理 legacy 上传。
4. 不改 contact 物理主键和下游关联模型。
5. 强化查询错误、写入错误、冲突记录，避免静默失败。
6. 上线前必须处理定时合并、表单、事件、索引和下游回归。

14. 质量自检

总分：26 / 26。可进入研发评审。