feat: add non-destructive EJ medicine sync

2026-09-10 11:09:26 +08:00
parent 27fbef9321
commit 17e9e7b6b6
6 changed files with 1087 additions and 0 deletions
@@ -0,0 +1,46 @@
+# EJ 药材非破坏性增量同步
+
+`ej-pharmacy:push-medicines` 将 ZYT 中启用且未删除的药材，通过现有 HMAC OpenAPI 增量推送到 EJ。
+
+## 不变式
+
+- EJ 只执行 `POST /api/openapi/v1/medicine-imports` 的新增/幂等确认，不删除或清空 EJ 药材。
+- 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`：一次性初始化并替换本地投影，不用于已有业务数据的生产环境增量同步。
+
+如果 EJ 已存在 source 映射，但对应药材被停用或软删除，EJ 会返回冲突；此时需要先在 EJ 药材管理中恢复该药材，再重新执行增量命令。