用途:这是一组数据模型设计规则,目标是让 schema 从一开始就支持从既有系统或第三方同步导入数据,做到幂等、可回滚,避免「迁移导入工程师」因缺少列或建模方式而受阻。应在设计阶段、在 ARCH 中设计任何导入之前应用到数据模型;这些规则在设计时成本很低,事后很难干净地补上。
三条核心规则:
- 可导入实体带 source_ref(来源标注)。任何可能由既有导出或第三方同步填充的实体,都应有一个可空且唯一的 source_ref 列,例如 source_ref text UNIQUE NULL,取值形如 "servicetitan:pricebook:8842"。它用作幂等重新导入的去重键,重新运行导出不会产生重复;命名空间为 {source}:{type}:{id},避免两个来源冲突;可空是因为原生创建的行没有来源。
- 可导入实体带 import_batch_id(回滚)。import_batch_id uuid NULL,用于标记一次导入运行写入的所有行。回滚即 delete where import_batch_id = ?。没有它就无法撤销,而没有撤销能力的导入用户不会信任去运行。
- 把真实世界的参与者建模为实体,而不是内联字段。客户、联系人、供应商、成员或租户都应有自己的表,即使 v1 只存名称和电话。因为导入会先填充这些实体,再填充依赖记录(报价、订单、预订);若在 Quote 上内联 customer_name,导入的客户就没有落脚点。内联参与者是最常见的迁移阻塞点。
辅助规则(成本低,防止静默数据丢失):金额用整数最小单位(*_cents),不要用浮点,因为导出数据带精确金额,浮点会破坏它。时间戳携带来源时区(存 UTC 加偏移,或使用 tz-aware),因为导出使用本地时间,模糊的 MM/DD 和 naive datetime 会丢数据。集成记账用的基础设施表要出现在模型里:outbound_message(幂等发送保护)和 processed_webhook_events(事件去重);集成工程师依赖它们,应明确列出。
检查清单(架构师在最终确定数据模型前运行):对数据模型中的每个实体,是否能从既有系统或第三方导入,若是则需有 source_ref 和 import_batch_id;是否是真实参与者(客户/联系人/供应商/成员),若是则应是独立实体而非内联字段;金额字段是否为整数最小单位;时间戳是否 tz-aware;是否列出了集成层需要的基础设施表(outbound_message、processed_webhook_events)。通过检查清单的数据模型,能为迁移导入工程师提供一个可幂等、可回滚导入的目标,不留下受阻的接缝。具体实现示例或代码请以原资料为准。