架构总览
系统采用**“接入层 → 规则引擎层 → 写回适配层”**三层架构，以配置驱动为核心，将业务规则与代码完全解耦。
Rendering diagram…
三层职责
| 层级 | 职责 | 关键能力 |
|---|---|---|
| 接入层 | 对接金蝶和旺店通 API，读取源单据并标准化为统一数据格式 | API 认证、分页拉取、数据标准化 |
| 规则引擎层 | 根据配置中心定义的规则，判断单据类型、路由目标、字段映射 | 条件分支、组织路由、字段转换、状态映射 |
| 写回适配层 | 将规则引擎处理后的数据，按目标系统 API 格式写入 | API 写入、幂等校验、结果记录 |
核心设计原则
原则一：配置驱动
所有业务规则存储在配置中心，代码中不出现任何硬编码的业务值：
| 配置项 | 说明 | 示例 |
|---|---|---|
| 组织编码 | 每个组织的唯一标识、名称、金蝶凭证 | A 组织 → org_a |
| 表单 ID | 每种业务单据在金蝶中的 formId | 分布式调出单 → STK_TRANSFEROUT |
| 字段映射 | 源单字段与目标单字段的对应关系 | 金蝶仓库编码 → 旺店通仓库编码 |
| 状态映射 | 源系统状态码到业务含义的映射 | 旺店通 status=95 → 已完成 |
| 路由规则 | 客户主体字段值对应的目标组织 | 客户主体=B → B 组织 |
原则二：幂等控制
每条业务流通过幂等键确保重复推送不会生成重复单据：
幂等键 = 源系统 + 源单号 + 业务类型
示例 = "kingdee" + "DBSO001" + "transfer_out"推送前先查询目标系统是否已存在对应单据，若存在则跳过（或更新），确保Exactly-Once语义。
原则三：全链路日志
每次推送记录以下信息，形成完整的同步日志链：
| 日志字段 | 说明 |
|---|---|
| 源系统 | kingdee / wdt |
| 源单号 | 金蝶或旺店通中的原始单据编号 |
| 业务类型 | transfer_out / sales_order / refund 等 |
| 目标系统 | kingdee / wdt |
| 目标组织 | 单据写入的目标组织编码 |
| 目标单号 | 写入成功后返回的目标单据编号 |
| 推送状态 | 成功 / 失败 / 跳过（幂等） |
| 错误信息 | 失败时的详细错误描述 |
| 重试次数 | 当前已重试的次数 |
| 创建时间 | 首次推送时间 |
| 更新时间 | 最后一次推送时间 |
原则四：异常重试
| 策略 | 说明 |
|---|---|
| 重试方式 | 指数退避（1s → 2s → 4s → 8s → 16s） |
| 最大重试次数 | 5 次 |
| 告警阈值 | 连续失败 3 次后触发告警 |
| 补偿机制 | 超过最大重试次数后标记为”需人工介入”，进入异常队列 |
数据流架构
金蝶 → 旺店通：调拨推送流
Rendering diagram…
旺店通 → 金蝶：销售回传流
Rendering diagram…
源组织 → 多目标组织：动态路由拆分流
Rendering diagram…
目标组织 → 采购订单：月度汇总流
Rendering diagram…
组件职责
| 组件 | 职责 | 输入 | 输出 |
|---|---|---|---|
| 金蝶读取适配器 | 调用金蝶 API 拉取指定 formId 的单据数据 | formId + 查询条件 | 标准化单据数据 |
| 旺店通读取适配器 | 调用旺店通 API 拉取销售/退款单据 | 接口名 + 查询条件 | 标准化单据数据 |
| 规则引擎 | 根据配置的条件判断、路由拆分、字段映射 | 标准化单据 + 配置规则 | 目标单据列表 |
| 金蝶写入适配器 | 将目标单据按金蝶 API 格式写入指定组织 | 目标单据 + 组织凭证 | 写入结果（目标单号） |
| 旺店通写入适配器 | 将目标单据按旺店通 API 格式写入 | 目标单据 + 接口配置 | 写入结果（目标单号） |
| 配置中心 | 管理所有业务规则配置 | 配置变更请求 | 配置项 |
| 同步日志服务 | 记录每次推送的完整信息 | 推送结果 | 日志记录 |
| 幂等控制服务 | 校验幂等键，防止重复推送 | 幂等键 | 是否已存在 |
| 异常重试服务 | 管理失败任务的重试调度 | 失败任务 | 重试结果 |
异常处理机制
异常分类
| 异常类型 | 处理策略 | 示例 |
|---|---|---|
| 网络超时 | 自动重试（指数退避） | 金蝶 API 响应超时 |
| 接口限流 | 自动重试 + 降速 | 旺店通 API 触发限频 |
| 字段校验失败 | 记录错误 + 跳过 + 告警 | 必填字段为空 |
| 组织凭证失效 | 告警 + 需人工更新凭证 | 金蝶 token 过期且无法自动刷新 |
| 目标系统异常 | 自动重试 + 告警 | 金蝶返回 500 错误 |
| 幂等冲突 | 跳过 + 记录日志 | 该源单号已成功推送过 |
补偿流程
Rendering diagram…
最后更新