客户编码已经唯一，维度表为什么还需要代理键？

结论：业务键回答“源里是谁”，代理键回答“仓里哪一行”

客户编码可能在源系统中唯一，但系统迁移、公司合并、编码复用或历史版本会让同一个值对应不同实体状态。

维度代理键由数仓控制，不承载业务含义，用于让事实稳定指向正确历史行。

多源业务键必须带来源命名空间

CRM 的客户 1001 和 ERP 的客户 1001 不一定是同一个人。映射表至少包含源系统、业务键、规范实体和有效期。

主数据确认合并前不要仅凭编码或名称直接共用代理键。

历史维度需要一实体多行

客户区域、等级或负责人变化时，Type 2 维度会生成新行和新代理键，旧事实仍连接旧版本。

事实加载应按业务事件时间查找当时有效行，而不是总连接当前最新记录。

代理键也要处理未知与迟到

事实先到时可连接明确的未知成员，维度到达后再按规则回填；不要用 0 同时代表未知、不适用和错误。

键生成必须幂等，重跑不能为同一维度版本创建不同代理键。

用迁移与历史场景验收

测试两个源使用相同编码、业务键变更、编码复用、客户合并、迟到维度和重跑，核对事实数量与历史属性。

BuildTable 可作为维度建模候选；代理键生成、历史匹配、实体映射和回填编排需逐项确认。

用三层身份模型避免把编码当实体

建议区分 source_business_key、canonical_entity_id 和 dimension_surrogate_key。第一层是某源系统当时的编码，必须带 source_system 命名空间；第二层是主数据确认后的跨源实体身份；第三层只标识维度表中的某一历史版本行。三者可相互映射，但不能合并成一个“客户 ID”字段。

例如 CRM 1001 与 ERP 1001 可能不是同一客户；CRM 的 1001 也可能在系统迁移后改成 A-1001。只有实体解析确认后，两个业务键才能指向同一 canonical_entity_id。若客户区域发生 Type 2 变化，仍会为同一实体生成新的 surrogate_key，让历史事实保留当时属性。

代理键生成必须稳定、无业务含义且可重放

代理键可以是序列整数、确定性哈希或平台生成 ID，关键是唯一、幂等和不携带业务意义。加载任务重跑时，同一维度版本必须得到同一键；不同版本不得因属性排序变化意外合并。若采用哈希，需要固定输入规范、空值处理和碰撞策略；若采用序列，需要用自然唯一约束防止并发重复。

不要把地区代码、年份或源系统塞进代理键让它“可读”。这会把当前业务规则固化到连接中，并在重组或迁移时制造重键。业务解释应来自维度属性和映射表，事实表只保存稳定外键。显示给业务人员的仍是业务编码或名称，而不是仓库代理键。

Type 2 匹配依赖事件时间和有效区间

维度版本通常保存 valid_from、valid_to、is_current，并对同一实体保证有效区间不重叠。事实加载时使用业务事件时间匹配 valid_from <= event_time < valid_to 的行，而不是使用加载当天的当前行。否则迟到一周的订单会错误连接到客户最新区域。

边界规则必须统一，例如 valid_to 采用开区间，时间精度按秒还是日期。当天属性变化若只能按日记录，需要说明事实无法区分日内前后。更正历史维度时要评估受影响事实并可控回填，不能只更新 is_current 就假设历史连接自动正确。

为未知、迟到、合并和拆分设计专门流程

事实先到而维度未到时，可连接“未知待补”成员并记录原始业务键，待维度到达后回填；not applicable、匿名、数据错误应使用不同特殊成员，避免一个 -1 掩盖所有原因。回填前后事实行数和金额必须守恒，只有维度外键变化。

客户合并与拆分更复杂。主数据把两个实体合并，不一定意味着历史事实都要重写；财务审计可能要求保留当时身份，而客户 360 需要当前统一视图。可同时提供 as-was 与 as-is 映射，通过桥表或不同语义模型服务，不要用一次破坏性更新消除业务历史。

迁移测试与 BuildTable 能力边界

验收覆盖跨源同码、业务键变更、编码复用、Type 2 日界、迟到事实、未知回填、实体合并拆分、并发加载和全量重跑。检查维度自然唯一、有效区间不重叠、事实引用完整、事实数量和度量守恒，并验证历史与当前视图差异符合规则。

BuildTable 可作为维度模型设计候选，但代理键生成、SCD、实体解析、迟到回填和桥表支持需按版本验证。并非所有维度都需要代理键：稳定、受控且无历史版本的小型日期等维度可使用业务键；选择依据是历史与集成需求，不是形式上的统一。

把身份规则固化为模型测试和运行监控

持续测试 source_system + business_key 的预期唯一、同一实体有效区间不重叠、current 行唯一、事实外键完整和特殊成员占比。加载监控新业务键、无法解析实体、迟到回填量、被重写事实和哈希碰撞；任何异常都能定位到批次和规则版本。代理键本身无需给业务查看，但映射证据必须可审计。

迁移时先双跑旧键与新键，按事实数量、金额、历史属性和当前实体视图对账，再切换消费层。不要在一个发布中同时更改实体解析、SCD 边界和事实回填，否则差异无法归因。完成后保留旧到新映射和回滚窗口，并向使用方解释 as-was 与 as-is 报告为何可能不同。

建立最小夹具覆盖同码不同源、同实体改码、编码复用、日界变化、迟到事实和合并拆分。预先写出每条事实应命中的代理键与属性，作为 ETL 和 AI 查询共同回归。任何“自动实体合并”都先进入待确认队列，只有主数据负责人批准后才影响规范实体视图。