DMTX 联系人组合主键能力 v3：dmd-cloud 参考与 PostgreSQL 适配方案

1. 一句话结论

DMTX 应该借鉴 dmd-cloud 的“业务唯一键 + 数据库唯一约束 + upsert 幂等写入”技术思想，但不应直接照搬它作为 DMTX contact 主表的身份解析模型。

原因不是 PostgreSQL 做不到，而是两套系统的联系人身份语义不同：

推荐方向：

保留 DMTX 默认 OR_MERGE 语义
  +
新增显式 SINGLE_UNIQUE / GROUPED_COMPOSITE 策略
  +
在明确策略下使用 PostgreSQL partial/expression/generated-column unique index
  +
局部场景使用 INSERT ... ON CONFLICT ... DO UPDATE ... RETURNING
  +
DataClean 仍负责 merge、副作用、冲突治理和下游一致性

2. v3 为什么单独成文

v2 已经明确 DMTX 当前现状：

1. DMTX 已支持多个 if_pk=true 主键字段。
2. Email/Mobile 可以取消主键，自定义字段可以设为主键。
3. 当前 DataClean 多主键运行时语义是 OR / 任一主键命中。
4. 客户要的酒店场景是 AND / 一组字段同时命中。

这次补充 dmd-cloud 后，需要额外回答一个工程问题：

答案是：可以借鉴局部技术，不建议直接迁移身份模型。

本方案不是替代 v2，而是 v2 的 companion：

3. dmd-cloud 已确认实现事实

3.1 unq_combi 来自索引 unq

在 dmd-cloud 中，unq_combi 不是独立的复杂规则对象，而是“字段是否在唯一索引 unq 中”的展示/配置结果。

关键事实：

典型逻辑：

$postedUniqueCombi = isset($post['unq_combi']) ? (array) $post['unq_combi'] : [];

foreach ($tableInfo as $name => $column) {
    if (in_array($name, $postedUniqueCombi, true)) {
        $newFields[$name] = $name;
    }
}

$tableChanges->dropIndex('unq')
    ->addIndex('unq', $newFields, true, $fieldExtras);

最终 SQL 类似：

ALTER TABLE `recipient_xxx`
  DROP INDEX `unq`,
  ADD UNIQUE INDEX `unq` (`A`, `B`);

3.2 默认 recipient 表也以 unq 作为唯一索引名

在 dmd-cloud 的 recipient 表创建逻辑中，默认 email 唯一索引也叫 unq：

UNIQUE KEY `unq` (email(60))

这说明 unq 是联系人业务唯一边界的固定索引名，unq_combi 是围绕该索引字段列表的配置能力。

3.3 写联系人时依赖 MySQL duplicate key

核心写入在：

[dmd-cloud]/src/WebPower/Dmdelivery/Core/Interactor/Recipient/LegacyRecipientStorer.php

其 SQL 结构是：

INSERT INTO `recipient_table` (...)
VALUES (...)
ON DUPLICATE KEY UPDATE
  id = LAST_INSERT_ID(id),
  ...

id=LAST_INSERT_ID(id) 的作用：

因此调用方可以用同一套返回逻辑拿到联系人 ID。

3.4 duplicate 不是只针对 unq

需要注意：MySQL ON DUPLICATE KEY UPDATE 不是指定某个索引触发，它会被任何 PRIMARY / UNIQUE 冲突触发。

也就是说，如果表上还有其他唯一索引，例如单字段唯一索引，那么 duplicate 分支不一定是 unq(A, B) 触发。

这点在 PostgreSQL 下不同，因为 PG 通常需要明确 conflict target：

ON CONFLICT (a, b) DO UPDATE

或：

ON CONFLICT ON CONSTRAINT uq_name DO UPDATE

3.5 dmd-cloud 的前缀索引是 MySQL 实现细节

dmd-cloud 对文本字段使用前缀长度：

这是 MySQL / MyISAM key length 约束下的实现细节，不应照搬到 DMTX PostgreSQL。

在 PostgreSQL 中，更推荐使用：

• 规范化列
• 生成列
• 表达式索引
• partial unique index

4. DMTX 当前 PostgreSQL / DataClean 真实语义

4.1 当前不是数据库唯一键驱动

DMTX 当前联系人识别主链路是：

DataClean.searchUserByPks
  -> AttributesUtils.userPks / setPkValue
  -> PostgreSQLSource.search
  -> DataClean.handleUsers
  -> SourceCommon.merge 或新增/更新
  -> CustomerService.saveContact / updateContact

关键代码事实：

当前查询更接近：

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

而不是：

select *
from contact
where email = ?
  and card_no = ?;

4.2 merge 是业务编排，不只是 DB update

DMTX 的 merge 不是单纯更新一行，它还包含：

因此，不能把：

DataClean 搜索 + merge + side effects

直接替换成：

INSERT ... ON CONFLICT DO UPDATE

数据库 upsert 只能完成“写哪一行”，无法自动完成 DMTX 当前 merge 的业务副作用。

4.3 DMTX 已经局部使用 PostgreSQL upsert

DMTX 并不是不能用 PG upsert，仓库里已有类似模式：

这说明：DMTX 可以使用 PG upsert，但更适合局部幂等表、状态表、事件表，而不是直接替代联系人身份解析主链路。

5. 核心语义差距

5.1 dmd-cloud 是唯一边界驱动

在 dmd-cloud 中，组合字段的含义是：

A + B + ... 命中 UNIQUE INDEX unq
  => 这是同一个 recipient
  => 通过 duplicate key 拿到已有 id
  => 按 overwrite 策略更新

5.2 DMTX 是候选集合 + merge 编排

在 DMTX 中，多个 PK 字段的含义是：

A 命中联系人 1 或 B 命中联系人 2
  => 都是候选
  => 多候选进入 merge
  => 触发标签、历史 ID、删除、事件等副作用

5.3 直接套用会改变业务行为

如果 DMTX 直接引入：

unique(email, card_no)

那么行为会变成：

这不是“实现方式变化”，而是“身份语义变化”。

6. PostgreSQL 适配原则

6.1 不照搬 MySQL LAST_INSERT_ID

PostgreSQL 等价思路是：

INSERT INTO contact_identity_map (...)
VALUES (...)
ON CONFLICT (company_id, identity_key)
DO UPDATE SET
  update_date = now()
RETURNING contact_id, created_at, update_date;

如果业务需要区分“新建还是已有”，不能依赖 MySQL affected_rows 规则，需要显式设计，例如：

• RETURNING xmax = 0 AS inserted，但这依赖 PG MVCC 细节，不建议作为长期产品契约。
• 在应用层先尝试 insert，捕获冲突后 update/select。
• 使用额外字段记录 first_seen_at / last_seen_at，由业务判断是否首次。
• 用 CTE 显式返回插入/更新状态。

推荐在方案层定义清楚：RETURNING 只能保证返回最终行，不天然等价于 dmd-cloud 的 isDuplicate。

6.2 PostgreSQL UNIQUE 对 NULL 的语义不同

PG 普通唯一索引允许多条 NULL：

create unique index uq_contact_email_card
on contact (email_norm, card_no_norm);

如果 email_norm 或 card_no_norm 为 NULL，多条记录可能不会冲突。

因此必须明确：

推荐使用 partial unique index：

create unique index concurrently uq_contact_card_email_norm
on contact (card_no_norm, email_norm)
where card_no_norm is not null
  and email_norm is not null;

6.3 表达式索引 vs 生成列

PG 可以写表达式唯一索引：

create unique index concurrently uq_contact_email_norm
on contact (lower(nullif(btrim(email), '')))
where nullif(btrim(email), '') is not null;

但如果后续要稳定使用 ON CONFLICT、易排查、易迁移，推荐使用生成列或显式规范化列：

alter table contact add column email_norm varchar;
alter table contact add column card_no_norm varchar;

create unique index concurrently uq_contact_card_email_norm
on contact (card_no_norm, email_norm)
where card_no_norm is not null
  and email_norm is not null;

原因：

• 查询语句更简单。
• 冲突目标更清晰。
• 可做 backfill 和冲突审计。
• 避免表达式与应用规范化逻辑不一致。

6.4 partial index 与 ON CONFLICT 的约束

如果使用 partial unique index，ON CONFLICT 也要匹配对应 conflict target 和 predicate，或者用约束名/索引推断方式设计清楚。

示意：

insert into contact_subscription (...)
values (...)
on conflict (company_id, customer_id, subscription_type_id)
where customer_id is not null
  do update set ...;

DMTX 已在 ContactSubscriptionService 中使用过类似模式：

on conflict (company_id, customer_id, subscription_type_id)
where customer_id is not null

以及：

on conflict (company_id, email, subscription_type_id)
where customer_id is null and email is not null

这比直接在 contact 主表上盲目加唯一索引更符合 DMTX 现有 PG 风格。

7. 哪些场景适合借鉴

8. 不建议直接改 contact 主表的原因

8.1 会弱化或改变当前去重

当前 DMTX 的 Email/Mobile 多主键是 OR 语义。直接改成组合唯一，会让“只命中 email”或“只命中 mobile”的行不再等价于同一联系人。

这可能使联系人数量上升，影响：

• 分群人数
• 旅程触达
• 评分结果
• 退订状态
• SCRM/企微联系人归属

8.2 会绕过 merge 副作用

SourceCommon.merge 和 DataClean merge 相关逻辑当前承担业务一致性。数据库 upsert 无法自动复刻：

• 标签 union
• WeCom 字段合并
• user_ids_str 历史身份维护
• loser 联系人删除
• merge event
• import 计数
• Huawei/Wechat 定制逻辑

因此即使未来用 PG unique 兜底，也应由 DataClean/Resolver 决定身份，再由 DB 兜底并发一致性，而不是 DB 单独决定完整业务流程。

8.3 旧导入器是独立分叉

ContacatImportDisposeService 当前有自己的 Email/Mobile 查询、合并、删除逻辑，未走 DataClean 通用 ifPk 机制。

如果 contact 表上突然新增唯一约束，旧导入器可能出现：

• 建索引失败：历史数据已重复。
• insert/update 冲突异常：旧逻辑未预期。
• 双重合并：应用层先 merge，DB 又触发 conflict。
• 统计错误：导入成功/失败与真实写入不一致。

所以 legacy 导入必须先纳入身份策略框架，不能让它先碰撞新约束。

9. 推荐 DMTX 身份策略分层

建议不要把 ifPk 直接映射为数据库唯一约束，而是显式建模策略。

9.1 OR_MERGE 保持现状

继续使用：

AttributesUtils.userPks
  -> PostgreSQLSource.search OR
  -> DataClean.handleUsers
  -> SourceCommon.merge

只补充：

• 查询异常不能当作无命中新增。
• 写入失败不能记成功。
• 定时合并要与新策略隔离。

9.2 SINGLE_UNIQUE 使用 PG upsert

适合：

• 外部会员 ID
• CRM ID
• DMD Contact Key
• unionid/openid 的规范化派生键

示例：

create unique index concurrently uq_contact_external_id_norm
on contact (external_id_norm)
where external_id_norm is not null;

写入：

insert into contact (contact_id, customer_id, external_id_norm, ...)
values (?, ?, ?, ...)
on conflict (external_id_norm)
where external_id_norm is not null
do update set
  update_date = now(),
  update_by = excluded.update_by
returning contact_id, customer_id;

9.3 GROUPED_COMPOSITE 使用组合唯一兜底

适合酒店：

cardNo + email

建议先落在 identity mapping 表，而不是直接在 contact 主表上改：

create table contact_identity_key (
  id bigserial primary key,
  company_id bigint not null,
  rule_code varchar(64) not null,
  identity_hash varchar(128) not null,
  contact_id varchar not null,
  customer_id varchar not null,
  normalized_values jsonb not null,
  create_date timestamp not null default current_timestamp,
  update_date timestamp not null default current_timestamp
);

create unique index concurrently uq_contact_identity_key
on contact_identity_key (company_id, rule_code, identity_hash);

写入：

insert into contact_identity_key (
  company_id,
  rule_code,
  identity_hash,
  contact_id,
  customer_id,
  normalized_values
)
values (?, ?, ?, ?, ?, ?::jsonb)
on conflict (company_id, rule_code, identity_hash)
do update set
  update_date = now()
returning contact_id, customer_id;

这样可以借鉴 dmd-cloud 的“唯一边界 + upsert”思想，同时避免直接改 contact 主表导致历史数据和 merge 副作用失控。

10. 推荐落地路径

P0：事实校准与数据审计

P1：局部幂等场景先试点

优先选择：

• 事件幂等表
• current-state 表
• identity mapping 表
• 订阅/标签聚合类表

这些场景 conflict target 明确，比较适合 PG ON CONFLICT。

P2：引入身份策略配置

新增策略枚举：

OR_MERGE
SINGLE_UNIQUE
GROUPED_COMPOSITE
MAPPING_TABLE

存量默认 OR_MERGE，新策略必须显式启用。

P3：酒店组合键 MVP

建议路径：

cardNo + email
  -> 规范化
  -> identity_hash
  -> contact_identity_key unique(company_id, rule_code, identity_hash)
  -> 返回 contact_id/customer_id
  -> DataClean 决定更新/新增/冲突

不要第一步就直接在 contact 主表建：

unique(card_no, email)

P4：是否进入 contact 主表改革

只有满足以下条件才考虑：

• 已完成历史重复清理。
• 已明确 survivor 规则。
• 已明确冲突回写策略。
• 已迁移 legacy 导入器。
• 已证明 DataClean 副作用可以完整保留。
• 已跑过灰度与回滚演练。

11. 测试与回滚

11.1 测试矩阵

11.2 回滚策略

12. 工作量评估

总估算：

13. 最终建议

1. dmd-cloud 值得借鉴，但借鉴的是思想，不是直接搬 SQL。

• MySQL LAST_INSERT_ID 换成 PG RETURNING。
• MySQL 前缀索引换成 PG 规范化列 / partial unique index。

1. DMTX 不能直接把 contact 主表身份解析改成 unique + upsert。

• 当前 DataClean 是 OR 匹配 + merge 副作用链。
• 直接替换会改变联系人数量、合并规则和下游一致性。

1. 推荐先从局部幂等能力借鉴。

• mapping 表、事件表、current-state 表、标签/状态聚合表。
• 这些场景 conflict target 清晰，更适合 PG ON CONFLICT。

1. 若要支持酒店组合键，建议先做 identity mapping 表。

• 用 company_id + rule_code + identity_hash 唯一。
• 返回 contact_id/customer_id 给 DataClean。
• DataClean 仍负责新增、更新、冲突和副作用。

1. contact 主表组合唯一只能作为后续高级阶段。

• 必须先清理历史重复。
• 必须迁移 legacy 导入。
• 必须证明 DataClean merge 副作用不会丢失。

一句话定稿：

14. 源码证据路径

dmd-cloud

DMTX

15. 质量自检

总分：20 / 20。可进入研发/架构评审。