🔄 舟谱×易订货 同步监控面板

快速上手

1. 客户：开启客户同步，完成首批映射；无编码客户需先在舟谱补码。
2. 商品：开启商品同步做首次全量；完成后可关闭商品定时，改在任务中心手工维护。
3. 库存：商品映射就绪后开启；无编码库存失败可忽略或清理。
4. 订单：客户+商品+库存稳定后，小批量灰度（建议 1～5 单）。
5. 状态回传：易订货流程采用方案 B（财务/出库/发货环节开启）后，再开「舟谱进度 → 易订货分步对齐」。

正式环境还需通过「运行总览」中的上线门禁（备份、恢复演练、告警等）。

页面导航

任务中心 · 按钮说明

顶部任务按钮（订单/商品/库存/客户…）

对应各同步类型的定时全量任务。仅当「系统设置 → 同步开关」里该类型为启用时可点；灰色表示开关未开。

商品维护

客户维护

单客户预览/同步、批量指定同步（逻辑同商品，指定同步不受客户定时开关限制）。

同步开关（系统设置 → 同步开关）

其他设置

同步周期 / 同步开关

「保存同步周期」只写间隔、批量、备份、Webhook；「保存同步开关」只写各同步开关与策略。两者互不影响，改哪页就点对应保存，避免误关已开启的订单/商品同步。

服务热读取部分项，开关或周期间隔变更后若任务未按预期运行，建议重启服务。

字段映射 / 单位换算

字段映射：舟谱→易订货（商品/客户）、易订货→舟谱（订单）的字段对应。单位换算表用于旧版单单位库存/订单兜底；启用「商品多单位」后，以商品同步写入的 goods_unit_map 为准。

订单作废相关

舟谱取消 cExtra、易订货/舟谱作废 API 路径由 probe 脚本探测后填入；作废不一致扫描用于发现两边状态不对齐的订单。

商品/库存数据重置（易订货初始化后）

位于运行总览底部。易订货商品被清空后，本地映射已全部失效，此工具用于一键清理并重来：

• 只清理商品/库存相关的映射、同步记录、单位映射、库存快照，并把商品水位设为指定日期（默认 2026-07-01 00:00:00）；不会触碰订单、客户、资金数据。
• 可勾选：一并清理库存快照、清理任务明细、清理运行日志、执行后自动开启「仅更新已映射商品」。
• 执行前务必：先在同步开关里关闭商品/库存同步，并在运行总览创建一次备份；再点「统计待清理」确认数量，最后「执行重置」（含二次确认）。
• 执行后：用任务中心「按编码同步」或「按品牌同步」把在售商品重新建好映射，再依次开启库存 → 订单。

CLI 脚本（与页面对应）

• node scripts/sync-goods-specified.js --code 编码 — 批量指定商品
• node scripts/sync-customers-specified.js — 指定客户
• node scripts/repair-order-ack.js — 订单 ACK 补偿
• node scripts/backup.js — 数据库备份

常见问题

商品同步失败 code=525 / 价格不能为空？

舟谱无零售价时，系统会用占位价 999 先建品，请在易订货人工改价。任务明细 request_summary 中 price: 为空或为 999 即此类。

关了商品同步还能加品吗？

可以。用任务中心「单商品/批量指定同步」，或 CLI sync-goods-specified.js。

易订货只看到一个小单位？

检查「商品多单位」是否启用，且舟谱该 SKU 有有效大单位（名称不同、pkgBaseRate > 1）。若商品已在多单位关闭时同步过，请到任务中心「批量补多单位」：先开启「商品多单位」与「商品更新」，统计后执行补写，无需删商品重建。

编码重复但列表查不到商品？

可能是之前同步创建的下架商品，按编码列表 API 查不到。到易订货后台搜编码，手工补映射或删除重复后再同步。

易订货初始化（清空商品）后怎么重建？

1. 同步开关关闭商品/库存同步，运行总览创建一次备份。
2. 运行总览底部「商品/库存数据重置」→「统计待清理」确认量 →「执行重置」（会把商品水位设到指定日期）。
3. 打开「仅更新已映射商品」，避免以后定时同步把老目录商品重新建回。
4. 用任务中心「按编码同步」或「按品牌同步」把在售商品重新建映射，再依次开启库存 → 订单同步。

商品同步报错「默认品牌 ID 不存在/不可用」？

易订货初始化后品牌通常为空，而建商品必须带品牌。请到系统设置 → 同步开关开启「品牌不存在时自动新建」——系统会按舟谱品牌名在易订货自动建品牌再建商品；改完需重启服务才生效。若想统一挂到某个品牌，也可在 API 连接里填「默认商品品牌 ID」作为兜底。

易订货订单的备注能带到舟谱吗？

可以。订单同步时会把易订货订单的备注写入舟谱销售单的整单备注（超长会截断）。无需额外配置，随订单同步自动生效。

易订货「同步状态」字段一直没回写？

请确认：①「订单成功回写『同步状态』」开关已开；② 该字段为文本时「已同步 选项 ID」留空；③ 下拉字段需填对应选项 ID。回写失败会记入待补偿队列，可在订单看板或任务中心 → 订单同步状态回写一键补写；订单/状态回传定时任务开头也会自动重试。

重启后要重新登录 / 日志出现 session-file-store 报错？

会话文件（data/sessions/*.json）只是临时登录态，不含业务数据，删除或过期只需重新登录一次即可，系统会自动重建。Windows 下偶发的 EPERM（写入 rename 撞锁）/ ENOENT（会话文件已删）已加入自愈重试与静默处理，功能不受影响；若持续大量报错再排查是否有多个服务实例或杀软锁文件。

状态回传失败：易订货订单已删除（404）？

易订货侧订单不存在时，状态回传会报 code=404，且会反复出现在异常列表、挡住 order_status 水位推进。

推荐操作（异常中心）：

1. 打开 异常中心，类型选 状态回传。
2. 找到对应易订货单号（如 DH-O-…），点该行灰色按钮 归档（勿点「重试」）。
3. 确认弹窗：系统写入 order_status 成功记录（canceled:ydh_archived_manual），移出待推送队列。
4. 到 任务中心 手动触发一次「订单状态回传」，确认 failed=0 后水位可正常推进。

勿单独使用「清除当前异常」：它只删除失败展示，不会标记为已处理，定时任务仍会再次失败。

可在 同步记录 按类型「状态回传」、单号搜索，核对是否已有 success 且 message 含 ydh_archived_manual。