zyt/docs/ej-pharmacy-incremental-medicine-sync.md

EJ 药材非破坏性增量同步

ej-pharmacy:push-medicines 将 ZYT 中启用且未删除的药材，通过现有 HMAC OpenAPI 增量推送到 EJ。

不变式

• EJ 只执行 POST /api/openapi/v1/medicine-imports 的新增/幂等确认，不删除或清空 EJ 药材。
• EJ 中由其他来源或人工录入的药材保持不变。
• ZYT 只增量写入或更新 EJ 返回的目录投影，不清空目录和映射。
• ZYT 中已停用或软删除的人工映射不重新启用。
• 命令默认 dry-run；只有同时提供 --apply 和确认令牌才执行远端导入。

先预检

cd /www/wwwroot/zyt/server
php think ej-pharmacy:push-medicines

输出示例：

dry-run source=654 candidates=654 batches=7 mapped=654 unmapped=0 preserved_inactive=0 remote_delete=0 local_delete=0

执行增量同步

cd /www/wwwroot/zyt/server
php think ej-pharmacy:push-medicines \
  --apply \
  --confirm=INCREMENTAL_NO_DELETE \
  --batch-size=100

可用 --run-id=<ID> 固定本次批次的幂等标识；ID 最长 25 位。若省略，命令使用稳定默认值 zyt-incremental，相同内容重试时复用同一 import ID。若旧批次已经完成、但需要修复 EJ 中后来被单独移除的药材，应提供新的维修 run ID，例如 --run-id=repair-20260910。

执行结果会分别报告 EJ 新增、EJ 已存在、本地目录新增/更新、本地映射新增/更新/不变，以及两侧删除数量；删除数量固定为零。

方向说明

• ej-pharmacy:push-medicines：ZYT → EJ，非破坏性增量新增或恢复远端缺项。
• ej-pharmacy:sync-catalog：EJ → ZYT，拉取 EJ 目录变化。
• ej-pharmacy:bootstrap-medicines：一次性初始化并替换本地投影，不用于已有业务数据的生产环境增量同步。

如果 EJ 已存在 source 映射，但对应药材被停用或软删除，EJ 会返回冲突；此时需要先在 EJ 药材管理中恢复该药材，再重新执行增量命令。