企业微信标签怎么和 CRM 双向同步

「双向」这个词要先拆掉

结论先给：同步方向不该按系统定，该按字段定。架构图上那根「企业微信侧 ↔ CRM」的双向箭头画着很顺，落到代码里就是同一个字段有两个写入方，而这正是所有同步事故共同的起点。

真按字段拆一遍会发现，绝大多数字段的方向是一眼可见的，需要开会讨论的只有三五个。先把无争议的定死，剩下的才值得花时间。

• 天然下行（自有客户库 → 企业微信侧）：来源渠道、生命周期阶段、按行为算出来的意向分层。计算逻辑在你自己库里，会话侧只是给一线扫一眼的展示位。
• 天然上行（会话侧 → CRM）：跟进中确认的事实 —— 对接人换了、需求变了、客户说了明确的拒绝理由。这些只在会话里产生，CRM 不可能自己知道。
• 看着两边都要：成交状态、客户等级。这类字段正确的处理不是双向，是拆成两个 —— 一个是 CRM 里的权威值，一个是「一线声称」，两者不一致本身就是要看的信号。

冲突判定：后写胜在这里是错的

跨系统同步的默认冲突策略是 last write wins，比时间戳、新的盖旧的。它成立需要两个前提：两侧时钟同源，两次写入语义对等。标签这个场景两条都不满足。

时钟不同源只是工程问题，加个统一时钟源或用平台给的序号能缓解。语义不对等才是致命的：程序按行为算出来的「高意向」，和销售把这个标签摘掉，不是同一件事的两个版本 —— 前者是一次计算结果，后者是一次人工否决。用时间先后给它们分胜负，等于宣布「谁动作晚谁有道理」，而人工否决无论早晚都该被记住。按「哪一侧动过」把冲突分成四格，处理方式完全不同。

1. 1只有一侧变：这不是冲突，正常同步。日常流量的绝大部分都在这一格，别为了另外三格把这一格搞复杂。
2. 2两侧改了同一字段：按 owner 裁决，非 owner 侧的那次修改不要丢弃，转成一条待复核记录。这一格没有正确的自动合并规则，任何自动合并都是在猜。
3. 3一侧改、一侧删：一律保留「改」，删除转成软删待确认。误删的恢复成本远高于多留一条待确认记录。
4. 4两侧都删：唯一能自动收敛的一格，直接落软删。

落到实现上，冲突判定需要的不是时间戳，是三样东西：字段级的 owner 表、每次写入带上的执行者标识（哪条自动化规则、哪个成员、哪次同步任务）、以及一个能装下「未被采纳的修改」的地方。第三样最常被省掉，省掉之后一线会发现自己的修改无声消失，从此不再相信这套系统 —— 这个信任一旦丢了，比任何数据问题都难修。

回环是双向同步真正的杀手

回环长这样：你用 wecomapi 的接口往会话侧写了一次标签，这次写入产生一条变更事件，同步任务把它当成一次新的用户变更写回 CRM，CRM 的变更又触发一次下行投影。它不报错，症状是标签在界面上来回闪、写入量莫名翻十倍、频控告警在没有业务活动的深夜响。

• 执行者标记：每次写入带上执行者标识，事件回来先看是不是自己的同步任务干的，是就直接丢。最直接，但依赖事件里能拿到足以区分来源的信息。
• 影子表取差集：为每个对象存一份「上次投影下去的内容」，每次下行只发差集，差集为空就不发。不依赖任何来源信息，天然收敛，代价只是一张表。
• 抑制窗口：同一对象同一字段在短窗口内的重复变更忽略掉。它会误伤真实的连续变更，只能当最后一道保险。

判断：影子表必须做，执行者标记有条件就做，抑制窗口只在前两条没兜住时兜底。三条都不做、指望「写的时候小心点别写回去」的方案，上线第一周就会出事，因为出事的从来不是你写的那条路径，是三个月后别人加的那条。

// 示意逻辑，函数与字段均为自拟；标签相关接口的精确字段与频率约束以 wecomapi 文档为准
const OWNER = require("./field-owner"); // 字段 -> 权威侧，配置化，三处共用

// 上行：会话侧事件回来，先判是不是自己写出去的回声
async function onTagChanged(evt) {
  if (evt.actor === SELF_SYNC_ACTOR) return;              // 执行者标记
  const shadow = await mirror.load(evt.customerId);
  if (shadow.equals(evt.tags)) return;                    // 和上次投影一致，是回声

  const patch = translate(evt);                           // 事件 -> 字段补丁
  for (const f of Object.keys(patch)) {
    if (OWNER[f] !== "wecom") { await review.push(evt, f); delete patch[f]; }
  }
  if (Object.keys(patch).length) await crm.patch(evt.customerId, patch, evt.id);
}

// 下行：只发差集，空差集不发；限速按账号算，不按全局算
async function project(customerId) {
  const want = await store.visibleTags(customerId);
  const have = await mirror.load(customerId);
  const { add, remove } = diff(have, want);
  if (!add.length && !remove.length) return;
  await limiter.byAccount(ownerOf(customerId)).run(() =>
    api.customerTag(customerId, { add, remove, actor: SELF_SYNC_ACTOR }));
  await mirror.save(customerId, want);
}

影子表顺带把下行写入量压到「标签实际变化量」这个量级，这笔账站内讲标签体系那篇已经算过，不重复。双向场景下值得多说一句的是它一表两用：同一份「上次投影内容」既是判回声的依据，也是写放大的护栏，所以比单向下行时更不能省。

上行这一侧：事件说的不是字段

下行是相对简单的一侧，难的是上行。上行的输入是事件流，事件说的是「刚才发生了什么」，CRM 要的是「这个字段现在等于什么」，这两者中间必须有一层翻译，直接 map 会把一堆没有业务含义的动作写进 CRM。

链路本身没什么花样：用 wecomapi 的事件回调收会话侧的变更，先快速 ACK 再入队异步处理，回调里不做任何跨系统写入。真正要额外做的是翻译层，它决定了 CRM 里最后长出什么。

1. 1事件 → 业务结论：「客户身上多了一个标签」这条事实本身不构成结论，能不能推出「升级为重点客户」，取决于谁打的、在哪个阶段打的。翻译规则集中写在一处，别散进各个消费者，否则同一条事件在两个消费者里会得出两个结论。
2. 2结论 → 字段补丁：写 CRM 一律用 patch，只带真正变化的字段。整行覆盖会把 CRM 里由其它系统维护的列一起抹掉，这类事故通常几周后才被人发现，而且很难追回。
3. 3补丁 → 幂等写入：以事件标识作幂等键，重复投递直接丢。事件重复是常态，不是异常。

还有一条最容易漏：上行必须允许「不翻译」。一线打的标签里有相当一部分是临时的、私人的、只对他自己有意义的，全量写进 CRM 换来的是几百个没人认领的字段值和一份没人敢用的报表。定一个上行白名单，白名单之外的只落进会话侧原始记录，需要时再捞。

裁决表与对账：双向系统必须有一张

单向同步的对账很省事，差异一律以源为准。双向系统没有全局的「源」，所以对账第一步不是比数据，是查 owner 表：这个差异落在哪个字段上，那个字段的权威侧在哪边，答案就在哪边。

这张表必须能被程序读，不能只活在设计文档里。落成配置之后，冲突裁决、回环判断、对账三处读同一份，改一次三处生效。写在文档里的结局是三处逐渐长歪，半年后没人说得清以哪个为准 —— 而这种不一致查起来极其费劲，因为每一处单独看都是对的。

• owner 侧和非 owner 侧一致的字段不用管，这是大多数，别让对账报告被它们淹没。
• 非 owner 侧的差异如果是人写的，进复核队列；如果是程序写的，直接按 owner 侧覆盖，不必留情。
• 「两侧都改过」的差异永远不自动修。它的数量应该很小，一旦变多，说明 owner 划分本身有问题，该回去改表而不是加规则。

对账的频率和分级是另一个话题，这里只强调一点：对账任务只产出差异单，不直接改数据。改数据交给独立的补偿任务，限速、幂等、留痕，并且修完能被下一轮对账验证。一个不会被验证的补偿，和不修没有本质区别。