主数据同步功能说明

功能概述

主数据同步由“分类同步 + 物料同步”两条独立链路组成：

分类同步：从 mdm_wlfl_code 全量拉取 01 / 0101 / 010101 结构的编码，生成 BSE 三层分类。
物料同步：从 mdm_material_view 拉取物料主数据，依赖已存在的分类信息完成入库。
物料同步会维护物料与分类绑定关系，并将非主表字段落入属性表。
同步结束后可选地向外部回调推送执行报告。

同步入口

分类同步接口

接口地址：POST /base/master-data-sync/categories
权限点：base:master-data-sync:categories
请求体：无（全量同步）
返回体：MasterDataCategorySyncReport

字段说明：

processedCategories：本次遍历的分类数量。
insertedCategories / updatedCategories：新增或更新的分类记录数。
missingParentReferences：外部数据缺失父级时的降级次数（会挂到根节点）。
success、message、startedAt、finishedAt：同物料同步。

⚠️ 分类同步需先于物料同步执行，确保 BSE 中已存在三层分类结构。

物料同步接口

接口地址：POST /base/master-data-sync/execute
权限点：base:master-data-sync:execute

请求体：

字段	类型	说明
`since`	`yyyy-MM-dd HH:mm:ss`	（可选）增量同步起始时间，空值表示全量。
`batchSize`	`Integer`	（可选）单批拉取条数，未填写则使用配置默认值。
`materialCodes`	`List<String>`	（可选）限定仅同步指定物料编码，留空同步全部。
`recordLimit`	`Long`	（可选）本次同步允许处理的最大记录数，留空则不做总量限制。

返回体为 MasterDataSyncReport，涵盖以下关键指标：

processedRecords：拉取并处理的记录数。
insertedMaterials / updatedMaterials：新增或更新的物料数量。
createdClassRelations / updatedClassRelations：物料与分类的关系处理次数。
insertedPropertyDefinitions / updatedPropertyDefinitions：属性定义的补齐情况。
insertedPropertyValues / updatedPropertyValues：属性值的写入情况。
success + message：执行状态及提示语。
startedAt / finishedAt：执行起止时间。
recordLimit：若请求指定了总量限制，会在报告中回显该值。

数据处理策略

属性字典：
- 程序会检查 MasterDataPropertyDefinition 枚举列出的全部属性（例如类别编码、规格、材质等）。
- 若属性定义不存在即创建，存在但名称/排序有差异会自动更新。
分类管理：
- 通过分类同步接口预先写入 01/0101/010101 三层数据，物料同步阶段仅检查并使用现有分类，如缺失则记录日志并跳过绑定。
物料主体：
- 按 material_code 进行 upsert，保留基础字段（物料编码、通用信息等）。
分类绑定：
- 若物料已有绑定但分类变化，则更新关系；否则创建新绑定。
属性值写入：
- 对比新旧值，仅在有变化或缺失时写入，避免无效更新。

配置项

在 application-*.yml 中通过 base.master-data-sync 节点进行控制：

base:
  master-data-sync:
    enabled: true                    # 是否开放同步入口
    batch-size: 500                  # 默认批量大小
    source-datasource-name: mdm      # 指向外部 MDM 的动态数据源
    notify-on-success: true          # 成功时是否回调
    notify-on-failure: true          # 失败时是否回调
    callback-url: http://example/callback
    callback-headers:
      X-TOKEN: xxx
    http:
      connect-timeout: 5s
      read-timeout: 30s
      write-timeout: 30s

⚠️ 请确保在 datasource.dynamic 中配置名为 mdm（或 source-datasource-name 指定值）的数据源，并指向外部 MDM 数据库。

数据源说明

master：默认业务库（BSE 表所在库），所有增删改依旧走 master 数据源，这部分无需额外配置。
mdm：主数据来源库（外部 MySQL）。MdmMaterialViewMapper、MdmMaterialCategoryMapper 均通过 @DS("mdm") 读取该库。

base.master-data-sync.source-datasource-name：若外部库名称不是 mdm，可在此覆盖，示例：

base:
   master-data-sync:
      source-datasource-name: mdm
datasource:
   dynamic:
      datasource:
         master: { ...本地库配置... }
         mdm: { url: jdbc:mysql://mdm-host/mdm, username: xxx, password: yyy }

✅ 强调：主数据读取始终走 mdm（或你在 source-datasource-name 中声明的别名），不要与默认 master 数据源混淆。

回调机制

当配置了 callbackUrl 时，系统会在同步结束后推送 JSON 结果。
推送内容为：

{
  "report": { ...MasterDataSyncReport... },
  "errorMessage": "可选的错误提示"
}

仅成功/失败分别受 notifyOnSuccess、notifyOnFailure 控制。
callbackHeaders 支持附加认证信息，如 Token、租户标识等。

常见问题排查

问题	检查点
数据源连接失败	确认 `mdm` 数据源配置、账号权限、网络可达性。
同步后未触发回调	检查 `callbackUrl`、`notify-on-*` 配置，以及目标地址是否可达。
属性值未生效	查看 `MasterDataPropertyDefinition` 是否包含该字段，或字段值是否为空/仅有空格。
只需同步单个物料	调用接口时在 `materialCodes` 中传入目标编码即可。

建议的使用流程

配置并验证外部数据源与 base.master-data-sync 参数。
先执行“分类同步接口”，确认三层分类齐全。
再执行“物料同步接口”，并确认报表数据、回调通知。
线上场景可定期以 since 参数驱动增量物料同步，也可按需指定 materialCodes 触发刷新；分类若有改动，可重新全量执行一次分类同步。

6.1 KiB Raw Blame History Unescape Escape