ERP 实施顾问的 5 大常用操作：从配置到排查的闭环

摘要：作为 ERP 实施顾问，你每天面对的是金蝶云星空 / 用友 / SAP 这类外部 ERP——对账结果能不能进 ERP、转换规则对不对、推送报错怎么查、状态卡在哪一态、凌晨告警怎么定位——这 5 件事构成了你的「日常 5 大常用操作」。本文按「配置 → 测试 → 调试 → 监控 → 排查」的顺序，把每一步的入口、契约、状态机、踩坑与 B 级干货拆给你看。无论你面对的是金蝶云星空的 9 个 handler、用友 NC 的 PULL 链，还是 SAP S/4 HANA 的 OData 推送，这 5 步走完就能完成一次完整的「集成中心 + 集成转换 + 推送落地」实施闭环。

关键词：ERP 实施、5 大常用操作、配置 ERP 集成、测试推送、调试转换、监控状态、排查问题、金蝶云星空、集成中心、集成转换、PULL、PUSH

第 0 分钟｜为什么是「5 大常用操作」

ERP 实施顾问的日常工作里，「让对账结果真的进到 ERP」从来不是一个动作——它是一组动作。从打开集成中心到客户月底关账，你实际要做的是 5 件事：

新手最常问的 3 个问题先答掉：

• 「5 步能不能少？」 ——不能。少了「配置」无法接入；少了「测试推送」上线即翻车；少了「调试转换」转换结果和金蝶对不上；少了「监控」失败没人知道；少了「排查」月结前才集中爆雷。
• 「5 步顺序能换吗？」 ——前 3 步严格串行（配置 → 测试 → 调试），后 2 步可并行。
• 「一个月重复几次？」 ——「配置 + 测试推送」每个客户一次（上线前）；「调试转换 + 监控状态 + 排查问题」每月一次。

下面 5 步走完一遍，每步配真实截图、踩坑与干货交替出现。

第 1 步｜配置 ERP 集成：集成中心 + 9 个 handler + configJson

进系统的第一件事是「找到入口」。左侧导航栏「集成中心」是所有 ERP 接入方案的家——每个方案背后是一个 integration_config + 一个 integration_handler（封装外部 API 调用），目前已落地 9 个 handler 覆盖金蝶云星空全部 PULL / PUSH 场景：

看到这张图时需要抓住 4 个关键信号：

1. 每个 handler 是一个独立方案——不要把多个单据类型塞进同一个方案，否则 configJson 会变成「if-else 巨塔」。
2. 场景按方向分类——health_check / ar-receivable.pull 是拉取方向；ar_receivable_bill / ar_receivable / ar_fin_receivable / cn_bank_transfer 是推送方向。PULL/PUSH 共用一个 handlerCode 但走不同 code 子路径。
3. 窗口 + 偏移参数——window=72h offset=30m 是拉取窗口（拉过去 72 小时到当前时间 + 偏移 30 分钟）。金蝶暂估单的过账日有 30 分钟延迟，不填 offset 会漏掉最后一小时的数据。
4. 右上有「新建方案」按钮——青绿色，配置客户接入的入口。

B 级干货 1｜9 个 handler 不是「金蝶全套」，是「金蝶云星空可落地全集」：handler 的拆分粒度 = 一个 docType（单据类型）。金蝶云星空 AR_receivable 应收单被拆成 3 个（应收单 / 财务应收单 / 销售收款单），因为它们的钩稽关系、Link 实体、立账类型完全不同——强行合并会让 isKingdeeSuccess(resp) 判定被「会话信息已丢失」污染（来源：金蝶云星空集成 SKILL §硬约束 #3）。

1.1｜新建方案的 5 个字段

点「新建方案」按钮，弹出配置面板。下面是金蝶云星空「健康检查」方案的字段全集：

1.2｜configJson 的 4 个关键键

configJson 是 handler 的运行时配置。金蝶云星空的 4 个键已踩过坑——

新手冷知识：configJson 的修改不会自动重启 handler——必须点「保存」按钮才会重新加载。系统为此在 save handler 里加了「加载校验」，保存后立即打一次 health_check 验证 acctId / storeId 是否能签名成功（来源：金蝶云星空集成 SKILL §硬约束 #4 — 写操作后必须用 isKingdeSuccess 判定）。

1.3｜集成中心架构全景

下面这张架构图把 3 大引擎（PULL / PUSH / 集成转换）的关系画得清清楚楚：

把 3 大引擎拆开看，对应到实施顾问的日常动作：

第 2 步｜测试推送：run-sync 同步调用 + health_check 验签

配置保存后，第一件事是先打一次连通性——health_check handler 是金蝶云星空的「握手仪式」，它不发任何业务数据，只验证 HMAC 双签名协议能不能正常工作。轻易云智能对账系统对 health_check 做了 4 类兜底：HMAC 签名失败自动重试 1 次、会话过期自动续期、HTTP 5xx 自动重试 3 次、参数缺失返回 400 而非静默跑空。

2.1｜同步 vs 异步：两种触发方式

系统提供 2 种触发集成方案的入口：

实施顾问的「测试推送」只走同步——你需要在浏览器看到响应结果：

curl -X POST http://localhost:4001/integrations/health_check/run-sync \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"params": {"configJson": {"acctId": "...", "storeId": "..."}}}'

2.2｜同步调用的 3 个坑

1. body 必须包 params——漏写 params 字段，会变成默认参数空跑（acctId 为空 → HMAC 签名失败 → 接口返回 200 但 success=false）。
2. run-sync 长调用客户端可能 abort——但服务端任务照常跑完——以 DB 状态为准，不要重复触发。
3. HTTP 200 不代表成功——金蝶云星空的写操作失败也返回 HTTP 200，必须用 isKingdeeSuccess(resp) 二次判定；失败用 extractKingdeeErrors(resp) 取完整报错原文（来源：金蝶云星空集成 SKILL §硬约束 #4）。

2.3｜金蝶 PUSH 推送流程图

下面这张流程图把金蝶云星空 PUSH 的 4 个阶段画出来——从 transform_documents 到金蝶审核：

把 4 个阶段拆开讲，对应到 ERP 实施顾问的测试推送操作：

B 级干货 2｜HMAC 双签名协议的实战价值：金蝶云星空的鉴权不是 OAuth，是 HMAC 双签名——AppData 用 HMAC_MD5（账号绑定），请求体用 HMAC_SHA256（防篡改）。这意味着 session 过期是业务错误（Errors[].Message="会话信息已丢失"），不是 HTTP 401——金蝶云星空 client 已内置失效重试机制（来源：金蝶云星空集成 SKILL §硬约束 #3）。

第 3 步｜调试转换：集成转换脚本 + transform_rules 四元键

测试推送通过后，下一步是调试集成转换脚本——这是把对账结果变成 ERP 单据的「数据塑形」层。集成转换脚本被定位为第 4 类沙箱脚本（parse / reconcile / allocate / transform），用同一套隔离 + 试跑端点。

3.1｜集成转换规则：164 条规则全景

调试转换的第一步是看清规则表——下图是金蝶云星空全部集成转换规则的真实截图：

把规则表按来源类型拆成 2 组：

B 级干货 3｜transform_rules 是脚本的「数据」不是脚本的「逻辑」：转换规则表的唯一键 = 五元 (sourceType, accountingItemId, amountKind, direction, targetSystem)。新增业务场景 = 加 transform_rules 规则，不是改脚本代码。脚本里的 transformRules 是预加载输入，运行时只读不写——这意味着「目标系统只是脚本与配置的取值，不是代码结构」（来源：integration-transform-script-development SKILL §硬约束 #7）。

3.2｜集成转换流程图：转换到推送的 5 阶段

下面这张流程图把集成转换的完整生命周期画出来：

把 5 个阶段拆开讲，对应到 ERP 实施顾问的调试操作：

3.3｜试跑端点的 4 大原则

调试转换的核心是试跑端点。对试跑端点有 4 大原则：

1. 同步：调用返回即出结果，30 秒超时闸。
2. 只读：沙箱内 query 只走 denylist 之外的模型。
3. 不落库：返回的 documents / unmatched 仅在 HTTP 响应里，不写 transform_documents。
4. 30s 闸：超过 30 秒同步超时，生产批次生成为异步 JobTask（沙箱 5min + 单事务落库上限 300s，整批原子、超限 FAILED 整体回滚）。

3.4｜调试转换的 3 个常见错误

跑试跑端点时最容易踩的 3 个错：

新手冷知识：试跑端点返回 documents[].entries[].sourceRefs 数组，每个 sourceRef 带 type（rule / planItem / materialItem / aggregation）——这是追踪「这行是怎么算出来的」的唯一线索。调试时拿不到这个数组，多半是脚本里没正确返回 sourceRefs（来源：integration-transform-script-development SKILL §4 沙箱契约）。

第 4 步｜监控状态：转换单据全局 + 推送状态机

转换批次生成后，你需要的是全局面板——一眼看出本月推送了多少张、失败了哪些、卡在哪个状态。下面是集成中心「转换单据」全局的真实截图：

看到这张图时需要抓住 4 个关键信号：

1. 状态分布数（最关键的 6 个数字）：预览中 64 + 已确认 10 + 推送中 0 + 已推送 154 + 推送失败 4 + 含异常体行 7。总 232 张，推送成功率 96.5%（154/160 推送过的）——剩余 64 张还在预览或确认中。
2. 外部单号已回填：列表里能看到 AP202607-0083Q / SKD260911008 这种外部单号——这意味着金蝶云星空 Save 接口成功响应并返回了 BillNo，系统自动写回 transform_documents.externalDocNo。
3. 含异常体行的 7 张——单据本身推送成功，但内部体行有 isAbnormal=true 的条目（如负额红字、SKU 空、缺 entryKey）。异常体行不阻断推送，但要人工复核。
4. 「推送失败 4」——这 4 张是实施顾问**第 5 步「排查问题」**的目标。

4.1｜推送状态机的 6 态

把转换单据的完整生命周期画成 6 态。轻易云智能对账系统的状态机与金蝶账套状态双向对齐——PUSHING 状态会主动取消已下推金蝶的中间态单据、FAILED 状态保留金蝶回执原始摘要：

4.2｜亚马逊欧洲站转换单据实例

下面是亚马逊欧洲站费用对账生成的 6 张转换单据，全部推送成功——这是「健康集成方案」的典型样本：

把这张图拆成 3 块给实施顾问讲：

新手冷知识：「同批次同目标」的设计是为了回滚原子性——一个批次的 6 张单据要么全推、要么全不推。如果中途某一张失败，整批会标 FAILED，需要先 UnAudit 全部已推单 + Delete 清理 + 「重新推送」（来源：金蝶云星空集成 SKILL §「清理测试单」命令 purge）。

4.3｜任务总览：异步任务执行结果

监控的最后一块拼图是「任务总览」——它告诉你异步任务跑了多久、失败了哪些：

实施顾问最常看的 3 个数字：

任何一项 < 100% 都要查 JobTask.errorMessage——异步任务的错误信息会原样落库，不要只看前端 toast。

第 5 步｜排查问题：集成推送日志 + 三段式 + 9 大失败原因

推送失败的 4 张单据怎么查？答案在「集成推送日志」——integration_push_logs 表的每一行记录一次金蝶调用的完整轨迹。

5.1｜三段式日志：请求体 / 响应体 / 摘要

对每一次金蝶调用写 3 段日志：

5.2｜9 大常见推送失败原因

把 2026-08-24 真实账套验证后总结的 9 大推送失败原因汇总：

B 级干货 4｜金蝶键名三态不可混用的工程价值：金蝶云星空的同一字段在 3 个接口里键名不同——Save / 元信息带 F 前缀（FEntityDetail / FCOSTID）；View 去前缀 / 用表别名（AP_PAYABLEENTRY / COSTID）；FieldKeys 带 F 前缀（FEntityDetail_FEntryID）。混用即报错「字段不存在」——这是金蝶云星空集成最隐蔽的坑（来源：金蝶云星空集成 SKILL §硬约束 #6）。

5.3｜金蝶探查脚本：从「报错」到「定位」的 6 步法

排查问题的高阶方法是用金蝶云星空的探查脚本直接验证字段、Link 关系、钩稽状态：

5.4｜批量重推

对失败的 4 张单据，不要逐张重推——用「批量重推」功能：

1. 在「转换单据」列表勾选 4 张 FAILED 单据。
2. 点「批量重新推送」按钮。
3. 系统按原 handler + 原 configJson 重发请求，自动忽略已成功单据。

新手冷知识：「批量重新推送」只重试 FAILED——已成功的 PUSHED 不会被覆盖。不要点「重新转换」按钮——会生成新批次、旧批次废弃，丢失外部单号映射关系。

常见问题｜5 大操作最容易踩的 5 个坑

把 ERP 实施顾问最容易踩的 5 个坑集中回答一遍：

Q1：configJson 改了但 health_check 仍报旧错——是不是没保存？

A：多半是点「保存」后没等「加载校验」跑完。configJson 修改不会自动重启 handler——必须等 save handler 的「加载校验」返回 success=true（来自金蝶云星空 health_check 响应），新配置才生效。

Q2：run-sync 返回 200 但 success=false——是网络问题吗？

A：不是网络问题——金蝶云星空的写操作失败也返回 HTTP 200。必须用 isKingdeeSuccess(resp) 二次判定；失败时用 extractKingdeeErrors(resp) 取完整报错原文（来源：金蝶云星空集成 SKILL §硬约束 #4）。

Q3：试跑端点返回的 documents 数组很完美，但生产批次却失败——为什么？

A：试跑端点是同步 + 不落库——它不写 transform_documents，但也不验证事务约束（如唯一索引、外键）。生产批次走异步 JobTask，单事务原子落库，超 300 秒会整体回滚 FAILED——这就是「试跑成功但生产失败」的最常见原因。

Q4：转换单据「推送失败 4」但 integration_push_logs 查不到日志——日志被删了？

A：不是被删——多半是日志被分页了。integration_push_logs 默认按时间倒序分页 20 条/页，失败日志可能在第 2~3 页。点页码翻到第 3 页找带 success=false 的行——查 3 段日志（请求体 / 响应体 / 摘要）定位错误。

Q5：批量重推后又失败了——是网络问题吗？

A：通常是金蝶账套层面的问题（如 FSettleTypeID 基础资料缺失、暂估单已下推过）。第一动作是看新生成的 integration_push_logs —— responseSummary 会精确告诉你哪个字段 / 哪个基础资料缺失。不要直接找金蝶运维——先在系统内看日志定位 5 分钟，定位不准再找金蝶更高效。

收尾｜从「5 大常用操作」到「月度集成闭环」

如果你已经按本文走完了一次「配置金蝶云星空 health_check → 测试推送 success → 调试 transform 试跑端点 → 监控转换单据全局 232 张 / 推送成功率 96.5% → 排查 4 张失败 + 批量重推」的完整流程，你已经完成了 ERP 实施顾问日常集成的 5 大常用操作闭环：

ERP 实施顾问日常做集成，看起来「只是配 1 个方案 + 跑 1 次试跑 + 看 1 张全局表 + 查 1 段日志」，背后是 9 个 handler × HMAC 双签名 × 集成转换 5 阶段 × 转换规则五元键 × 推送 6 态状态机 × 三段式日志 × 9 大失败原因对照 × 6 步探查法。轻易云智能对账系统把传统 ERP 集成工具压缩成「5 个入口 + 1 张全局表 + 30 秒同步试跑 + 三段式日志诊断」——从「配置到排查」全闭环，新实施顾问跟着本文走 1 遍 + 实操 1 个客户 = 当天即可上线一个金蝶云星空集成方案。

接下来 9.5.5 会带你从「ERP 实施顾问视角」切到「CTO 视角」——关注部署、监控、性能、安全、知识库的运维主线。

面向开发者：本文涉及的 9 个金蝶云星空 handler、HMAC 双签名协议、集成转换 5 阶段、transform_rules 五元键、推送 6 态状态机、三段式日志的完整实现，可以在项目仓库 .opencode/skills/kingdee-cloud-galaxy-integration/SKILL.md（金蝶云星空集成工作方式指南）、.opencode/skills/integration-transform-script-development/SKILL.md（集成转换脚本开发标准）两个 SKILL 文档里查完整实现、探查脚本清单（scripts/integrations/kingdee-cloud-galaxy/）、硬约束 6 条与 9 大失败原因对照表。