# EJ 药材非破坏性增量同步

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

## 不变式

- EJ 只执行 `POST /api/openapi/v1/medicine-imports` 的新增/幂等确认，不删除或清空 EJ 药材。
- EJ 中由其他来源或人工录入的药材保持不变。
- ZYT 已同步且在 EJ 中仍正常启用的药材保持名称、价格、库存和编码不变。
- ZYT 已同步但在 EJ 中被软删除的药材恢复原记录和原 `medicine_code`；被停用的药材重新启用。
- ZYT 后续新增、且从未同步过的药材追加到 EJ，并初始化零库存。
- ZYT 只增量写入或更新 EJ 返回的目录投影，不清空目录和映射。
- ZYT 中已停用或软删除的人工映射不重新启用。
- 命令默认 dry-run；只有同时提供 `--apply` 和确认令牌才执行远端导入。

## 先预检

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

输出示例：

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

## 执行增量同步

```bash
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`：一次性初始化并替换本地投影，不用于已有业务数据的生产环境增量同步。

同步范围以 `source_system=zyt` 和 `source_medicine_id` 标识来源。恢复和重新启用只作用于原来由 ZYT 同步过去的药材，因此不会修改 EJ 自己新增的药材。